github.com/caddyserver/certmagic v0.23.0: PEMEncodePrivateKey

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 github.com/caddyserver/certmagic.PEMEncodePrivateKey in pkg:golang/github.com/caddyserver/certmagic@v0.23.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/caddyserver/certmagic@v0.23.0
Demonstrate these symbols/APIs:
  - github.com/caddyserver/certmagic.PEMEncodePrivateKey
Constraints:
  - executionContext: node
Required runtime conditions:
  - ecosystem: npm
  - language: javascript
  - moduleSystem: cjs
  - packageManager: npm@10.9.8
  - runtime: node@22.23.2

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.

package sample

import (
	"crypto/ecdsa"
	"crypto/ed25519"
	"crypto/elliptic"
	"crypto/rand"
	"crypto/rsa"
	"encoding/pem"
	"testing"

	"github.com/caddyserver/certmagic"
)

func TestContractPEMEncodePrivateKey(t *testing.T) {
	// 1. PEMEncodePrivateKey encodes RSA private keys to PEM format with RSA PRIVATE KEY block
	rsaKey, err := rsa.GenerateKey(rand.Reader, 2048)
	if err != nil {
		t.Fatalf("rsa.GenerateKey failed: %v", err)
	}
	rsaPEM, err := certmagic.PEMEncodePrivateKey(rsaKey)
	if err != nil {
		t.Fatalf("PEMEncodePrivateKey for RSA failed: %v", err)
	}
	rsaBlock, _ := pem.Decode(rsaPEM)
	if rsaBlock == nil {
		t.Fatalf("failed to decode RSA PEM block")
	}
	if rsaBlock.Type != "RSA PRIVATE KEY" {
		t.Errorf("expected block type 'RSA PRIVATE KEY', got %q", rsaBlock.Type)
	}

	// 2. PEMEncodePrivateKey encodes ECDSA private keys (P-256 and P-384) to PEM format with EC PRIVATE KEY block
	ecP256Key, err := ecdsa.GenerateKey(elliptic.P256(), rand.Reader)
	if err != nil {
		t.Fatalf("ecdsa.GenerateKey(P256) failed: %v", err)
	}
	ecP256PEM, err := certmagic.PEMEncodePrivateKey(ecP256Key)
	if err != nil {
		t.Fatalf("PEMEncodePrivateKey for ECDSA P-256 failed: %v", err)
	}
	ecBlock, _ := pem.Decode(ecP256PEM)
	if ecBlock == nil {
		t.Fatalf("failed to decode ECDSA PEM block")
	}
	if ecBlock.Type != "EC PRIVATE KEY" {
		t.Errorf("expected block type 'EC PRIVATE KEY', got %q", ecBlock.Type)
	}

	ecP384Key, err := ecdsa.GenerateKey(elliptic.P384(), rand.Reader)
	if err != nil {
		t.Fatalf("ecdsa.GenerateKey(P384) failed: %v", err)
	}
	ecP384PEM, err := certmagic.PEMEncodePrivateKey(ecP384Key)
	if err != nil {
		t.Fatalf("PEMEncodePrivateKey for ECDSA P-384 failed: %v", err)
	}
	ecP384Block, _ := pem.Decode(ecP384PEM)
	if ecP384Block == nil || ecP384Block.Type != "EC PRIVATE KEY" {
		t.Errorf("expected ECDSA P-384 PEM block type 'EC PRIVATE KEY'")
	}

	// 3. PEMEncodePrivateKey encodes Ed25519 private keys to PEM format with ED25519 PRIVATE KEY block
	_, edKey, err := ed25519.GenerateKey(rand.Reader)
	if err != nil {
		t.Fatalf("ed25519.GenerateKey failed: %v", err)
	}
	edPEM, err := certmagic.PEMEncodePrivateKey(edKey)
	if err != nil {
		t.Fatalf("PEMEncodePrivateKey for Ed25519 failed: %v", err)
	}
	edBlock, _ := pem.Decode(edPEM)
	if edBlock == nil {
		t.Fatalf("failed to decode Ed25519 PEM block")
	}
	if edBlock.Type != "ED25519 PRIVATE KEY" {
		t.Errorf("expected block type 'ED25519 PRIVATE KEY', got %q", edBlock.Type)
	}

	// 4. PEMEncodePrivateKey encodes keys generated by certmagic.StandardKeyGenerator
	kg := certmagic.StandardKeyGenerator{KeyType: certmagic.ED25519}
	genKey, err := kg.GenerateKey()
	if err != nil {
		t.Fatalf("StandardKeyGenerator.GenerateKey failed: %v", err)
	}
	genPEM, err := certmagic.PEMEncodePrivateKey(genKey)
	if err != nil {
		t.Fatalf("PEMEncodePrivateKey for StandardKeyGenerator key failed: %v", err)
	}
	if len(genPEM) == 0 {
		t.Fatalf("expected non-empty PEM bytes from generated key")
	}

	// 5. PEMDecodePrivateKey successfully decodes PEMEncodePrivateKey output back to private keys
	decodedRSA, err := certmagic.PEMDecodePrivateKey(rsaPEM)
	if err != nil {
		t.Fatalf("PEMDecodePrivateKey(rsaPEM) failed: %v", err)
	}
	if _, ok := decodedRSA.(*rsa.PrivateKey); !ok {
		t.Errorf("expected *rsa.PrivateKey from decoded RSA PEM, got %T", decodedRSA)
	}

	decodedEC, err := certmagic.PEMDecodePrivateKey(ecP256PEM)
	if err != nil {
		t.Fatalf("PEMDecodePrivateKey(ecP256PEM) failed: %v", err)
	}
	if _, ok := decodedEC.(*ecdsa.PrivateKey); !ok {
		t.Errorf("expected *ecdsa.PrivateKey from decoded ECDSA PEM, got %T", decodedEC)
	}

	decodedEd, err := certmagic.PEMDecodePrivateKey(edPEM)
	if err != nil {
		t.Fatalf("PEMDecodePrivateKey(edPEM) failed: %v", err)
	}
	if _, ok := decodedEd.(ed25519.PrivateKey); !ok {
		t.Errorf("expected ed25519.PrivateKey from decoded Ed25519 PEM, got %T", decodedEd)
	}

	// 6. PEMEncodePrivateKey rejects nil and unsupported private key types with an error
	if _, err := certmagic.PEMEncodePrivateKey(nil); err == nil {
		t.Errorf("expected error for nil private key, got nil")
	}
	if _, err := certmagic.PEMEncodePrivateKey("invalid_key_type"); err == nil {
		t.Errorf("expected error for unsupported string key type, got nil")
	}
}

{"case":{"caseId":"case:sha256:461c25fb37dbcc4455e4eecca19e59476a31e3bf3fa1b2e67aedace0d5c89223","contract":["PEMEncodePrivateKey encodes RSA private keys to PEM format with RSA PRIVATE KEY block","PEMEncodePrivateKey encodes ECDSA private keys (P-256 and P-384) to PEM format with EC PRIVATE KEY block","PEMEncodePrivateKey encodes Ed25519 private keys to PEM format with ED25519 PRIVATE KEY block","PEMEncodePrivateKey encodes keys generated by certmagic.StandardKeyGenerator","PEMDecodePrivateKey successfully decodes PEMEncodePrivateKey output back to private keys","PEMEncodePrivateKey rejects nil and unsupported private key types with an error"],"goal":"verify github.com/caddyserver/certmagic.PEMEncodePrivateKey in pkg:golang/github.com/caddyserver/certmagic@v0.23.0","kind":"HOW","packages":["pkg:golang/github.com/caddyserver/certmagic@v0.23.0"],"schemaVersion":1,"symbols":["github.com/caddyserver/certmagic.PEMEncodePrivateKey"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"golang","language":"go","libc":"glibc","libcVersion":"2.39","moduleSystem":"go-modules","os":"linux","osVersionBucket":"24","packageManager":"go","runtime":"go","runtimeVersion":"1.26","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/caddyserver/certmagic@v0.23.0"],"schemaVersion":1,"subject":"pkg:golang/github.com/caddyserver/certmagic@v0.23.0","symbols":["github.com/caddyserver/certmagic.PEMEncodePrivateKey"],"verifierAdapter":"golang@1"}

module sample

go 1.25.0

require github.com/caddyserver/certmagic v0.25.4

require (
	github.com/caddyserver/zerossl v0.1.5 // indirect
	github.com/klauspost/cpuid/v2 v2.3.0 // indirect
	github.com/libdns/libdns v1.1.1 // indirect
	github.com/mholt/acmez/v3 v3.1.6 // indirect
	github.com/miekg/dns v1.1.72 // indirect
	github.com/zeebo/blake3 v0.2.4 // indirect
	go.uber.org/multierr v1.11.0 // indirect
	go.uber.org/zap v1.27.1 // indirect
	go.uber.org/zap/exp v0.3.0 // indirect
	golang.org/x/crypto v0.50.0 // indirect
	golang.org/x/mod v0.35.0 // indirect
	golang.org/x/net v0.53.0 // indirect
	golang.org/x/sync v0.20.0 // indirect
	golang.org/x/sys v0.43.0 // indirect
	golang.org/x/text v0.36.0 // indirect
	golang.org/x/tools v0.44.0 // indirect
)

code.pfad.fr/check v1.1.0 h1:GWvjdzhSEgHvEHe2uJujDcpmZoySKuHQNrZMfzfO0bE=
code.pfad.fr/check v1.1.0/go.mod h1:NiUH13DtYsb7xp5wll0U4SXx7KhXQVCtRgdC96IPfoM=
github.com/caddyserver/certmagic v0.25.4 h1:8eIXh0HC3MsGnNo8One+BCxMGTbe5zb/oz+2KsxBFQg=
github.com/caddyserver/certmagic v0.25.4/go.mod h1:YVs43D5+H/Dckt4bTga1KSO/xYfFBfVZainGDywYPAA=
github.com/caddyserver/zerossl v0.1.5 h1:dkvOjBAEEtY6LIGAHei7sw2UgqSD6TrWweXpV7lvEvE=
github.com/caddyserver/zerossl v0.1.5/go.mod h1:CxA0acn7oEGO6//4rtrRjYgEoa4MFw/XofZnrYwGqG4=
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
github.com/go-jose/go-jose/v4 v4.1.3 h1:CVLmWDhDVRa6Mi/IgCgaopNosCaHz7zrMeF9MlZRkrs=
github.com/go-jose/go-jose/v4 v4.1.3/go.mod h1:x4oUasVrzR7071A4TnHLGSPpNOm2a21K9Kf04k1rs08=
github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
github.com/klauspost/cpuid/v2 v2.3.0 h1:S4CRMLnYUhGeDFDqkGriYKdfoFlDnMtqTiI/sFzhA9Y=
github.com/klauspost/cpuid/v2 v2.3.0/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
github.com/letsencrypt/challtestsrv v1.4.2 h1:0ON3ldMhZyWlfVNYYpFuWRTmZNnyfiL9Hh5YzC3JVwU=
github.com/letsencrypt/challtestsrv v1.4.2/go.mod h1:GhqMqcSoeGpYd5zX5TgwA6er/1MbWzx/o7yuuVya+Wk=
github.com/letsencrypt/pebble/v2 v2.10.0 h1:Wq6gYXlsY6ubqI3hhxsTzdyotvfdjFBxuwYqCLCnj/U=
github.com/letsencrypt/pebble/v2 v2.10.0/go.mod h1:Sk8cmUIPcIdv2nINo+9PB4L+ZBhzY+F9A1a/h/xmWiQ=
github.com/libdns/libdns v1.1.1 h1:wPrHrXILoSHKWJKGd0EiAVmiJbFShguILTg9leS/P/U=
github.com/libdns/libdns v1.1.1/go.mod h1:4Bj9+5CQiNMVGf87wjX4CY3HQJypUHRuLvlsfsZqLWQ=
github.com/mholt/acmez/v3 v3.1.6 h1:eGVQNObP0pBN4sxqrXeg7MYqTOWyoiYpQqITVWlrevk=
github.com/mholt/acmez/v3 v3.1.6/go.mod h1:5nTPosTGosLxF3+LU4ygbgMRFDhbAVpqMI4+a4aHLBY=
github.com/miekg/dns v1.1.72 h1:vhmr+TF2A3tuoGNkLDFK9zi36F2LS+hKTRW0Uf8kbzI=
github.com/miekg/dns v1.1.72/go.mod h1:+EuEPhdHOsfk6Wk5TT2CzssZdqkmFhf8r+aVyDEToIs=
github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
github.com/stretchr/testify v1.8.1/go.mod h1:w2LPCIKwWwSfY2zedu0+kehJoqGctiVI29o6fzry7u4=
github.com/zeebo/assert v1.1.0 h1:hU1L1vLTHsnO8x8c9KAR5GmM5QscxHg5RNU5z5qbUWY=
github.com/zeebo/assert v1.1.0/go.mod h1:Pq9JiuJQpG8JLJdtkwrJESF0Foym2/D9XMU5ciN/wJ0=
github.com/zeebo/blake3 v0.2.4 h1:KYQPkhpRtcqh0ssGYcKLG1JYvddkEA8QwCM/yBqhaZI=
github.com/zeebo/blake3 v0.2.4/go.mod h1:7eeQ6d2iXWRGF6npfaxl2CU+xy2Fjo2gxeyZGCRUjcE=
github.com/zeebo/pcg v1.0.1 h1:lyqfGeWiv4ahac6ttHs+I5hwtH/+1mrhlCtVNQM2kHo=
github.com/zeebo/pcg v1.0.1/go.mod h1:09F0S9iiKrwn9rlI5yjLkmrug154/YRW6KnnXVDM/l4=
go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
go.uber.org/zap v1.27.1 h1:08RqriUEv8+ArZRYSTXy1LeBScaMpVSTBhCeaZYfMYc=
go.uber.org/zap v1.27.1/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
go.uber.org/zap/exp v0.3.0 h1:6JYzdifzYkGmTdRR59oYH+Ng7k49H9qVpWwNSsGJj3U=
go.uber.org/zap/exp v0.3.0/go.mod h1:5I384qq7XGxYyByIhHm6jg5CHkGY0nsTfbDLgDDlgJQ=
golang.org/x/crypto v0.50.0 h1:zO47/JPrL6vsNkINmLoo/PH1gcxpls50DNogFvB5ZGI=
golang.org/x/crypto v0.50.0/go.mod h1:3muZ7vA7PBCE6xgPX7nkzzjiUq87kRItoJQM1Yo8S+Q=
golang.org/x/mod v0.35.0 h1:Ww1D637e6Pg+Zb2KrWfHQUnH2dQRLBQyAtpr/haaJeM=
golang.org/x/mod v0.35.0/go.mod h1:+GwiRhIInF8wPm+4AoT6L0FA1QWAad3OMdTRx4tFYlU=
golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=
golang.org/x/net v0.53.0/go.mod h1:JvMuJH7rrdiCfbeHoo3fCQU24Lf5JJwT9W3sJFulfgs=
golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
golang.org/x/sys v0.43.0 h1:Rlag2XtaFTxp19wS8MXlJwTvoh8ArU6ezoyFsMyCTNI=
golang.org/x/sys v0.43.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
golang.org/x/text v0.36.0 h1:JfKh3XmcRPqZPKevfXVpI1wXPTqbkE5f7JA92a55Yxg=
golang.org/x/text v0.36.0/go.mod h1:NIdBknypM8iqVmPiuco0Dh6P5Jcdk8lJL0CUebqK164=
golang.org/x/tools v0.44.0 h1:UP4ajHPIcuMjT1GqzDWRlalUEoY+uzoZKnhOjbIPD2c=
golang.org/x/tools v0.44.0/go.mod h1:KA0AfVErSdxRZIsOVipbv3rQhVXTnlU6UhKxHd1seDI=
gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package sample

import (
	"crypto"
	"errors"
	"fmt"

	"github.com/caddyserver/certmagic"
)

// GenerateAndEncodeKey generates a new private key of the specified type (e.g. ED25519, RSA2048, etc.)
// and encodes it into PEM format using certmagic.PEMEncodePrivateKey.
func GenerateAndEncodeKey(keyType certmagic.KeyType) ([]byte, crypto.PrivateKey, error) {
	keyGen := certmagic.StandardKeyGenerator{KeyType: keyType}
	privKey, err := keyGen.GenerateKey()
	if err != nil {
		return nil, nil, fmt.Errorf("generate key: %w", err)
	}

	pemBytes, err := certmagic.PEMEncodePrivateKey(privKey)
	if err != nil {
		return nil, nil, fmt.Errorf("PEM encode private key: %w", err)
	}

	return pemBytes, privKey, nil
}

// EncodePrivateKey takes an existing crypto.PrivateKey (RSA, ECDSA, Ed25519) and encodes it to PEM.
func EncodePrivateKey(key crypto.PrivateKey) ([]byte, error) {
	if key == nil {
		return nil, errors.New("private key cannot be nil")
	}
	return certmagic.PEMEncodePrivateKey(key)
}

// DecodePrivateKey decodes PEM encoded private key bytes back into a crypto.PrivateKey.
func DecodePrivateKey(pemBytes []byte) (crypto.PrivateKey, error) {
	return certmagic.PEMDecodePrivateKey(pemBytes)
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/caddyserver/certmagic.PEMEncodePrivateKey in pkg:golang/github.com/caddyserver/certmagic@v0.23.0",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/caddyserver/certmagic@v0.23.0"
  ],
  "symbols": [
    "github.com/caddyserver/certmagic.PEMEncodePrivateKey"
  ],
  "constraints": {
    "executionContext": "node"
  },
  "runtimeConditions": {
    "ecosystem": "npm",
    "language": "javascript",
    "moduleSystem": "cjs",
    "packageManager": "npm@10.9.8",
    "runtime": "node@22.23.2"
  }
}