challtestsrv

README

Challenge Test Server

The challtestsrv package offers a library/command that can be used by test code to respond to HTTP-01 and DNS-01 ACME challenges.

Important note: The challtestsrv command and library are for TEST USAGE ONLY. It is trivially insecure, offering no authentication. Only use challtestsrv in a controlled test environment.

Install

go install ./test/challtestsrv/...

Standalone challtestsrv Command

The standalone challtestsrv binary lets you run HTTP-01 and DNS-01 challenge servers that external programs can add/remove challenge responses to using a management HTTP API.

This is used by the Boulder integration tests to easily add/remove TXT records for DNS-01 challenges for the chisel.py ACME client.

Usage

Usage of challtestsrv:
  -dns01 string
       Comma separated bind addresses/ports for DNS-01 challenges and fake DNS data. Set empty to disable. (default ":8053")
  -http01 string
       Comma separated bind addresses/ports for HTTP-01 challenges. Set empty to disable. (default ":5002")
  -management string
       Bind address/port for management HTTP interface (default ":8055")

To disable a challenge type, set the bind address to "". E.g.:

• To run HTTP-01 only: challtestsrv -dns01 ""
• To run DNS-01 only: challtestsrv -http01 ""

Management Interface

Note: These examples assume the default management interface of :8056

Adding an HTTP-01 challenge response for the token "aaaa" with the content "bbbb":

curl -X POST -d '{"token":"aaaa", "content":"bbbb"}' localhost:8056/add-http01

Deleting an HTTP-01 challenge response for the token "aaaa":

curl -X POST -d '{"token":"aaaa"}' localhost:8056/del-http01

Adding a DNS-01 TXT challenge for the host "_acme-challenge.example.com." with the value "bbbb":

curl -X POST -d '{"host":"_acme-challenge.example.com.", "value":"bbbb"}' localhost:8056/set-txt

Deleting a DNS-01 TXT challenge for the host "_acme-challenge.example.com.":

curl -X POST -d '{"host":"_acme-challenge.example.com."}' localhost:8056/clear-txt

The test/challtestsrv package

The test/challtestsrv package can be used as a library by another program to avoid needing to manage an external challtestsrv binary or use the HTTP based management interface. This is used by the Boulder load-generator command to manage its own in-process HTTP-01 challenge server.

Usage

Create a challenge server responding to HTTP-01 challenges on ":8888" and DNS-01 challenges on ":9999" and "10.0.0.1:9998":

  import "github.com/letsencrypt/boulder/test/challtestsrv"

  challSrv, err := challtestsrv.New(challsrv.Config{
    HTTPOneAddr: []string{":8888"},
    DNSOneAddr: []string{":9999", "10.0.0.1:9998"},
  })
  if err != nil {
    panic(err)
  }

Run the Challenge server and subservers:

  // Start the Challenge server in its own Go routine
  go challSrv.Run()

Add an HTTP-01 response for the token "aaa" and the value "bbb", defer cleaning it up again:

  challSrv.AddHTTPOneChallenge("aaa", "bbb")
  defer challSrv.DeleteHTTPOneChallenge("aaa")

Add a DNS-01 TXT response for the host "_acme-challenge.example.com." and the value "bbb", defer cleaning it up again:

  challSrv.AddDNSOneChallenge("_acme-challenge.example.com.", "bbb")
  defer challSrv.DeleteHTTPOneChallenge("_acme-challenge.example.com.")

Stop the Challenge server and subservers:

  // Shutdown the Challenge server
  challSrv.Shutdown()

Documentation

Index

• type ChallSrv
  • func New(config Config) (*ChallSrv, error)
  • func (s *ChallSrv) AddDNSOneChallenge(host, content string)
  • func (s *ChallSrv) AddHTTPOneChallenge(token, content string)
  • func (s *ChallSrv) AddTLSALPNChallenge(host, content string)
  • func (s *ChallSrv) DeleteDNSOneChallenge(host string)
  • func (s *ChallSrv) DeleteHTTPOneChallenge(token string)
  • func (s *ChallSrv) DeleteTLSALPNChallenge(host string)
  • func (s *ChallSrv) GetDNSOneChallenge(host string) []string
  • func (s *ChallSrv) GetHTTPOneChallenge(token string) (string, bool)
  • func (s *ChallSrv) GetTLSALPNChallenge(host string) (string, bool)
  • func (s *ChallSrv) Run()
  • func (s *ChallSrv) ServeChallengeCertFunc(k *ecdsa.PrivateKey) func(*tls.ClientHelloInfo) (*tls.Certificate, error)
  • func (s *ChallSrv) ServeHTTP(w http.ResponseWriter, r *http.Request)
  • func (s *ChallSrv) Shutdown()
• type Config

Types

type ChallSrv

type ChallSrv struct {
	// contains filtered or unexported fields
}

ChallSrv is a multi-purpose challenge server. Each ChallSrv may have one or more ACME challenges it provides servers for.

func New

func New(config Config) (*ChallSrv, error)

New constructs and returns a new ChallSrv instance with the given Config.

func (*ChallSrv) AddDNSOneChallenge

func (s *ChallSrv) AddDNSOneChallenge(host, content string)

AddDNSOneChallenge adds a TXT record for the given host with the given content.

func (*ChallSrv) AddHTTPOneChallenge

func (s *ChallSrv) AddHTTPOneChallenge(token, content string)

AddHTTPOneChallenge adds a new HTTP-01 challenge for the given token and content.

func (*ChallSrv) AddTLSALPNChallenge

func (s *ChallSrv) AddTLSALPNChallenge(host, content string)

AddTLSALPNChallenge adds a new TLS-ALPN-01 key authorization for the given host

func (*ChallSrv) DeleteDNSOneChallenge

func (s *ChallSrv) DeleteDNSOneChallenge(host string)

DeleteDNSOneChallenge deletes a TXT record for the given host.

func (*ChallSrv) DeleteHTTPOneChallenge

func (s *ChallSrv) DeleteHTTPOneChallenge(token string)

DeleteHTTPOneChallenge deletes a given HTTP-01 challenge token.

func (*ChallSrv) DeleteTLSALPNChallenge

func (s *ChallSrv) DeleteTLSALPNChallenge(host string)

DeleteTLSALPNChallenge deletes the key authorization for a given host

func (*ChallSrv) GetDNSOneChallenge

func (s *ChallSrv) GetDNSOneChallenge(host string) []string

GetDNSOneChallenge returns a slice of TXT record values for the given host. If the host does not exist in the challenge response data then nil is returned.

func (*ChallSrv) GetHTTPOneChallenge

func (s *ChallSrv) GetHTTPOneChallenge(token string) (string, bool)

GetHTTPOneChallenge returns the HTTP-01 challenge content for the given token (if it exists) and a true bool. If the token does not exist then an empty string and a false bool are returned.

func (*ChallSrv) GetTLSALPNChallenge

func (s *ChallSrv) GetTLSALPNChallenge(host string) (string, bool)

GetTLSALPNChallenge checks the s.tlsALPNOne map for the given host. If it is present it returns the key authorization and true, if not it returns an empty string and false.

func (*ChallSrv) Run

func (s *ChallSrv) Run()

Run starts each of the ChallSrv's challengeServers.

func (*ChallSrv) ServeChallengeCertFunc

func (s *ChallSrv) ServeChallengeCertFunc(k *ecdsa.PrivateKey) func(*tls.ClientHelloInfo) (*tls.Certificate, error)

func (*ChallSrv) ServeHTTP

func (s *ChallSrv) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP handles an HTTP request. If the request path has the ACME HTTP-01 challenge well known prefix as a prefix and the token specified is known, then the challenge response contents are returned.

func (*ChallSrv) Shutdown

func (s *ChallSrv) Shutdown()

Shutdown gracefully stops each of the ChallSrv's challengeServers.

type Config

type Config struct {
	Log *log.Logger
	// HTTPOneAddrs are the HTTP-01 challenge server bind addresses/ports
	HTTPOneAddrs []string
	// DNSOneAddrs are the DNS-01 challenge server bind addresses/ports
	DNSOneAddrs []string
	// TLSALPNOneAddrs are the TLS-ALPN-01 challenge server bind addresses/ports
	TLSALPNOneAddrs []string
}

Config holds challenge server configuration