github.com/mholt/acmez/v3 v3.1.2: TLSALPN01ChallengeCert

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/mholt/acmez/v3.TLSALPN01ChallengeCert in pkg:golang/github.com/mholt/acmez/v3@v3.1.2
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:golang/github.com/mholt/acmez/v3@v3.1.2
Demonstrate these symbols/APIs:
  - github.com/mholt/acmez/v3.TLSALPN01ChallengeCert

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:bcec36f0c5a6382e268a3216691d75d8f2de1912dc9d1767dcb22252e2678b02","contract":["TLSALPN01ChallengeCert generates a non-nil self-signed tls.Certificate with Subject CommonName \"ACME challenge\" and DNS SAN matching the challenge identifier.","TLSALPN01ChallengeCert attaches a critical acmeValidation-v1 extension (OID 1.3.6.1.5.5.7.1.31) containing the ASN.1-marshaled SHA-256 digest of KeyAuthorization.","TLSALPN01ChallengeCert converts internationalized domain names (IDN) in the challenge identifier to ASCII punycode SAN.","TLSALPN01ChallengeCert certificate successfully negotiates an in-memory TLS handshake using ACMETLS1Protocol (\"acme-tls/1\") ALPN.","TLSALPN01ChallengeCert returns an error when provided with an invalid domain identifier."],"goal":"verify github.com/mholt/acmez/v3.TLSALPN01ChallengeCert in pkg:golang/github.com/mholt/acmez/v3@v3.1.2","kind":"HOW","packages":["pkg:golang/github.com/mholt/acmez/v3@v3.1.2"],"schemaVersion":1,"symbols":["github.com/mholt/acmez/v3.TLSALPN01ChallengeCert"]},"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/github.com/mholt/acmez/v3@v3.1.2"],"schemaVersion":1,"subject":"pkg:golang/github.com/mholt/acmez/v3@v3.1.2","symbols":["github.com/mholt/acmez/v3.TLSALPN01ChallengeCert"],"verifierAdapter":"golang@1"}

module sample

go 1.26.6

require github.com/mholt/acmez/v3 v3.1.2

require (
	golang.org/x/crypto v0.27.0 // indirect
	golang.org/x/net v0.29.0 // indirect
	golang.org/x/text v0.18.0 // indirect
)

github.com/mholt/acmez/v3 v3.1.2 h1:auob8J/0FhmdClQicvJvuDavgd5ezwLBfKuYmynhYzc=
github.com/mholt/acmez/v3 v3.1.2/go.mod h1:L1wOU06KKvq7tswuMDwKdcHeKpFFgkppZy/y0DFxagQ=
golang.org/x/crypto v0.27.0 h1:GXm2NjJrPaiv/h1tb2UH8QfgC/hOf/+z0p6PT8o1w7A=
golang.org/x/crypto v0.27.0/go.mod h1:1Xngt8kV6Dvbssa53Ziq6Eqn0HqbZi5Z6R0ZpwQzt70=
golang.org/x/net v0.29.0 h1:5ORfpBpCs4HzDYoodCDBbwHzdR5UrLBZ3sOnUJmFoHo=
golang.org/x/net v0.29.0/go.mod h1:gLkgy8jTGERgjzMic6DS9+SP0ajcu6Xu3Orq/SpETg0=
golang.org/x/text v0.18.0 h1:XvMDiNzPAl0jr17s6W9lcaIhGUfUORdGCNsuLmPG224=
golang.org/x/text v0.18.0/go.mod h1:BuEKDfySbSR4drPmRPG/7iBdf8hvFMuRexcpahXilzY=

package main

import (
	"fmt"
	"os"

	"github.com/mholt/acmez/v3"
	"github.com/mholt/acmez/v3/acme"
)

func main() {
	// Prepare an ACME TLS-ALPN-01 challenge with a domain and key authorization
	challenge := acme.Challenge{
		Type:             "tls-alpn-01",
		Identifier:       acme.Identifier{Type: "dns", Value: "example.com"},
		KeyAuthorization: "sample-token-12345.sample-account-thumbprint-67890",
	}

	// Generate the self-signed TLS certificate with the acmeValidation-v1 extension
	cert, err := acmez.TLSALPN01ChallengeCert(challenge)
	if err != nil {
		fmt.Fprintf(os.Stderr, "failed to generate TLS-ALPN-01 challenge cert: %v\n", err)
		os.Exit(1)
	}

	fmt.Printf("Generated challenge certificate with %d certificate chain entry\n", len(cert.Certificate))
	fmt.Printf("Supported ALPN protocol: %s\n", acmez.ACMETLS1Protocol)
}

{
  "schemaVersion": 1,
  "goal": "verify github.com/mholt/acmez/v3.TLSALPN01ChallengeCert in pkg:golang/github.com/mholt/acmez/v3@v3.1.2",
  "kind": "HOW",
  "packages": [
    "pkg:golang/github.com/mholt/acmez/v3@v3.1.2"
  ],
  "symbols": [
    "github.com/mholt/acmez/v3.TLSALPN01ChallengeCert"
  ]
}

package main

import (
	"bytes"
	"crypto/sha256"
	"crypto/tls"
	"crypto/x509"
	"encoding/asn1"
	"fmt"
	"net"
	"os"

	"github.com/mholt/acmez/v3"
	"github.com/mholt/acmez/v3/acme"
)

var idPEACMEIdentifierV1 = asn1.ObjectIdentifier{1, 3, 6, 1, 5, 5, 7, 1, 31}

func main() {
	keyAuth := "test-token-12345.test-account-thumbprint-67890"
	domain := "example.com"

	// Assertion 1: TLSALPN01ChallengeCert generates a non-nil self-signed tls.Certificate with Subject CommonName "ACME challenge" and DNS SAN matching the challenge identifier.
	chal := acme.Challenge{
		Type:             "tls-alpn-01",
		Identifier:       acme.Identifier{Type: "dns", Value: domain},
		KeyAuthorization: keyAuth,
	}

	cert, err := acmez.TLSALPN01ChallengeCert(chal)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: TLSALPN01ChallengeCert returned error: %v\n", err)
		os.Exit(1)
	}
	if cert == nil || len(cert.Certificate) == 0 {
		fmt.Fprintf(os.Stderr, "FAIL: TLSALPN01ChallengeCert returned nil or empty certificate\n")
		os.Exit(1)
	}

	leaf, err := x509.ParseCertificate(cert.Certificate[0])
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: x509.ParseCertificate failed: %v\n", err)
		os.Exit(1)
	}
	if leaf.Subject.CommonName != "ACME challenge" {
		fmt.Fprintf(os.Stderr, "FAIL: CommonName mismatch, got %q, want %q\n", leaf.Subject.CommonName, "ACME challenge")
		os.Exit(1)
	}
	if len(leaf.DNSNames) != 1 || leaf.DNSNames[0] != domain {
		fmt.Fprintf(os.Stderr, "FAIL: DNSNames mismatch, got %v, want [%s]\n", leaf.DNSNames, domain)
		os.Exit(1)
	}

	// Assertion 2: TLSALPN01ChallengeCert attaches a critical acmeValidation-v1 extension (OID 1.3.6.1.5.5.7.1.31) containing the ASN.1-marshaled SHA-256 digest of KeyAuthorization.
	var foundACMEExt bool
	expectedDigest := sha256.Sum256([]byte(keyAuth))
	for _, ext := range leaf.Extensions {
		if ext.Id.Equal(idPEACMEIdentifierV1) {
			foundACMEExt = true
			if !ext.Critical {
				fmt.Fprintf(os.Stderr, "FAIL: acmeValidation-v1 extension must be marked critical\n")
				os.Exit(1)
			}
			var val []byte
			_, err := asn1.Unmarshal(ext.Value, &val)
			if err != nil {
				fmt.Fprintf(os.Stderr, "FAIL: failed to unmarshal acmeValidation-v1 ASN.1: %v\n", err)
				os.Exit(1)
			}
			if !bytes.Equal(val, expectedDigest[:]) {
				fmt.Fprintf(os.Stderr, "FAIL: acmeValidation-v1 digest mismatch\n")
				os.Exit(1)
			}
		}
	}
	if !foundACMEExt {
		fmt.Fprintf(os.Stderr, "FAIL: acmeValidation-v1 extension not found in certificate\n")
		os.Exit(1)
	}

	// Assertion 3: TLSALPN01ChallengeCert converts internationalized domain names (IDN) in the challenge identifier to ASCII punycode SAN.
	idnChal := acme.Challenge{
		Type:             "tls-alpn-01",
		Identifier:       acme.Identifier{Type: "dns", Value: "bücher.example"},
		KeyAuthorization: keyAuth,
	}
	idnCert, err := acmez.TLSALPN01ChallengeCert(idnChal)
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: TLSALPN01ChallengeCert failed on IDN domain: %v\n", err)
		os.Exit(1)
	}
	leafIDN, err := x509.ParseCertificate(idnCert.Certificate[0])
	if err != nil {
		fmt.Fprintf(os.Stderr, "FAIL: parse IDN cert failed: %v\n", err)
		os.Exit(1)
	}
	if len(leafIDN.DNSNames) != 1 || leafIDN.DNSNames[0] != "xn--bcher-kva.example" {
		fmt.Fprintf(os.Stderr, "FAIL: IDN DNSNames mismatch, got %v, want [xn--bcher-kva.example]\n", leafIDN.DNSNames)
		os.Exit(1)
	}

	// Assertion 4: TLSALPN01ChallengeCert certificate successfully negotiates an in-memory TLS handshake using ACMETLS1Protocol ("acme-tls/1") ALPN.
	serverConf := &tls.Config{
		Certificates: []tls.Certificate{*cert},
		NextProtos:   []string{acmez.ACMETLS1Protocol},
	}
	clientConf := &tls.Config{
		InsecureSkipVerify: true,
		ServerName:         domain,
		NextProtos:         []string{acmez.ACMETLS1Protocol},
	}

	clientConn, serverConn := net.Pipe()
	errCh := make(chan error, 2)

	go func() {
		s := tls.Server(serverConn, serverConf)
		errCh <- s.Handshake()
		_ = s.Close()
	}()

	go func() {
		c := tls.Client(clientConn, clientConf)
		err := c.Handshake()
		if err == nil {
			state := c.ConnectionState()
			if state.NegotiatedProtocol != acmez.ACMETLS1Protocol {
				errCh <- fmt.Errorf("negotiated ALPN protocol mismatch: got %q, want %q", state.NegotiatedProtocol, acmez.ACMETLS1Protocol)
				_ = c.Close()
				return
			}
		}
		errCh <- err
		_ = c.Close()
	}()

	for i := 0; i < 2; i++ {
		if err := <-errCh; err != nil {
			fmt.Fprintf(os.Stderr, "FAIL: in-memory TLS handshake failed: %v\n", err)
			os.Exit(1)
		}
	}

	// Assertion 5: TLSALPN01ChallengeCert returns an error when provided with an invalid domain identifier.
	invalidChal := acme.Challenge{
		Type:             "tls-alpn-01",
		Identifier:       acme.Identifier{Type: "dns", Value: "xn--invalid_punycode"},
		KeyAuthorization: keyAuth,
	}
	if _, err := acmez.TLSALPN01ChallengeCert(invalidChal); err == nil {
		fmt.Fprintf(os.Stderr, "FAIL: TLSALPN01ChallengeCert expected error on invalid domain\n")
		os.Exit(1)
	}

	fmt.Println("PASS: all TLSALPN01ChallengeCert contract assertions passed.")
}