challtestsrv

package module
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 5, 2023 License: MPL-2.0 Imports: 21 Imported by: 6

README

Challenge Test Server

Build Status Coverage Status Go Report Card GolangCI

The challtestsrv package offers a library that can be used by test code to respond to HTTP-01, DNS-01, and TLS-ALPN-01 ACME challenges. The challtestsrv package can also be used as a mock DNS server letting developers mock A, AAAA, CNAME, and CAA DNS data for specific hostnames. The mock server will resolve up to one level of CNAME aliasing for accepted DNS request types.

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

For example this package 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/pebble/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.")

Get the history of HTTP requests processed by the challenge server for the host "example.com":

requestHistory := challSrv.RequestHistory("example.com", challtestsrv.HTTPRequestEventType)

Clear the history of HTTP requests processed by the challenge server for the host "example.com":

challSrv.ClearRequestHistory("example.com", challtestsrv.HTTPRequestEventType)

Stop the Challenge server and subservers:

  // Shutdown the Challenge server
  challSrv.Shutdown()

For more information on the package API see Godocs and the associated package sourcecode.

Documentation

Overview

Package challtestsrv provides a trivially insecure acme challenge response server for rapidly testing HTTP-01, DNS-01 and TLS-ALPN-01 challenge types.

Index

Constants

View Source 
const ACMETLS1Protocol = "acme-tls/1"

ALPN protocol ID for TLS-ALPN-01 challenge https://tools.ietf.org/html/draft-ietf-acme-tls-alpn-01#section-5.2

Variables

View Source 
var IDPeAcmeIdentifier = asn1.ObjectIdentifier{1, 3, 6, 1, 5, 5, 7, 1, 31}

IDPeAcmeIdentifier is the identifier defined in https://tools.ietf.org/html/draft-ietf-acme-tls-alpn-04#section-5.1 id-pe OID + 31 (acmeIdentifier)

Functions

This section is empty.

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. It is safe to use concurrently.

func New 

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

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

func (*ChallSrv) AddDNSAAAARecord 

func (s *ChallSrv) AddDNSAAAARecord(host string, addresses []string)

AddDNSAAAARecord adds IPv6 addresses that will be returned when querying for AAAA records for the given host.

func (*ChallSrv) AddDNSARecord 

func (s *ChallSrv) AddDNSARecord(host string, addresses []string)

AddDNSARecord adds IPv4 addresses that will be returned when querying for A records for the given host.

func (*ChallSrv) AddDNSCAARecord 

func (s *ChallSrv) AddDNSCAARecord(host string, policies []MockCAAPolicy)

AddDNSCAARecord adds mock CAA records that will be returned when querying CAA for the given host.

func (*ChallSrv) AddDNSCNAMERecord added in v1.1.0 

func (s *ChallSrv) AddDNSCNAMERecord(host string, value string)

AddDNSCNAMERecord sets a CNAME record that will be used like an alias when querying for other DNS records for the given host.

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) AddDNSServFailRecord added in v1.2.0 

func (s *ChallSrv) AddDNSServFailRecord(host string)

AddDNSServFailRecord configures the chall srv to return SERVFAIL responses for all queries for the given host.

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) AddHTTPRedirect 

func (s *ChallSrv) AddHTTPRedirect(path, targetURL string)

AddHTTPRedirect adds a redirect for the given path to the given URL.

func (*ChallSrv) AddRequestEvent added in v1.0.1 

func (s *ChallSrv) AddRequestEvent(event RequestEvent)

AddRequestEvent adds a RequestEvent to the server's request history. It is appeneded to a list of RequestEvents indexed by the event's Type().

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) ClearRequestHistory added in v1.0.1 

func (s *ChallSrv) ClearRequestHistory(hostname string, typ RequestEventType)

ClearRequestHistory clears the server's request history for the given hostname and event type.

func (*ChallSrv) DeleteDNSAAAARecord 

func (s *ChallSrv) DeleteDNSAAAARecord(host string)

DeleteDNSAAAARecord deletes any IPv6 addresses that will be returned when querying for A records for the given host.

func (*ChallSrv) DeleteDNSARecord 

func (s *ChallSrv) DeleteDNSARecord(host string)

DeleteDNSARecord deletes any IPv4 addresses that will be returned when querying for A records for the given host.record for the given host.

func (*ChallSrv) DeleteDNSCAARecord 

func (s *ChallSrv) DeleteDNSCAARecord(host string)

DeleteDNSCAARecord deletes any CAA policies that will be returned when querying CAA for the given host.

func (*ChallSrv) DeleteDNSCNAMERecord added in v1.1.0 

func (s *ChallSrv) DeleteDNSCNAMERecord(host string)

DeleteDNSCAMERecord deletes any CNAME alias set for the given host.

func (*ChallSrv) DeleteDNSOneChallenge 

func (s *ChallSrv) DeleteDNSOneChallenge(host string)

DeleteDNSOneChallenge deletes a TXT record for the given host.

func (*ChallSrv) DeleteDNSServFailRecord added in v1.2.0 

func (s *ChallSrv) DeleteDNSServFailRecord(host string)

DeleteDNSServFailRecord configures the chall srv to no longer return SERVFAIL responses for all queries for the given host.

func (*ChallSrv) DeleteHTTPOneChallenge 

func (s *ChallSrv) DeleteHTTPOneChallenge(token string)

DeleteHTTPOneChallenge deletes a given HTTP-01 challenge token.

func (*ChallSrv) DeleteHTTPRedirect 

func (s *ChallSrv) DeleteHTTPRedirect(path string)

DeleteHTTPRedirect deletes a redirect for the given path.

func (*ChallSrv) DeleteTLSALPNChallenge 

func (s *ChallSrv) DeleteTLSALPNChallenge(host string)

DeleteTLSALPNChallenge deletes the key authorization for a given host

func (*ChallSrv) GetDNSAAAARecord 

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

GetDNSAAAARecord returns a slice of IPv6 addresses (in string form) that will be returned when querying for A records for the given host.

func (*ChallSrv) GetDNSARecord 

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

GetDNSARecord returns a slice of IPv4 addresses (in string form) that will be returned when querying for A records for the given host.

func (*ChallSrv) GetDNSCAARecord 

func (s *ChallSrv) GetDNSCAARecord(host string) []MockCAAPolicy

GetDNSCAARecord returns a slice of mock CAA policies that will be returned when querying CAA for the given host.

func (*ChallSrv) GetDNSCNAMERecord added in v1.1.0 

func (s *ChallSrv) GetDNSCNAMERecord(host string) string

GetDNSCNAMERecord returns a target host if a CNAME is set for the querying host and an empty string otherwise.

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) GetDNSServFailRecord added in v1.2.0 

func (s *ChallSrv) GetDNSServFailRecord(host string) bool

GetDNSServFailRecord returns true when the chall srv has been configured with AddDNSServFailRecord to return SERVFAIL for all queries to the given host.

func (*ChallSrv) GetDefaultDNSIPv4 

func (s *ChallSrv) GetDefaultDNSIPv4() string

GetDefaultDNSIPv4 gets the default IPv4 address used for A query responses (in string form), or an empty string if no default is being used.

func (*ChallSrv) GetDefaultDNSIPv6 

func (s *ChallSrv) GetDefaultDNSIPv6() string

GetDefaultDNSIPv6 gets the default IPv6 address used for AAAA query responses (in string form), or an empty string if no default is being used.

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) GetHTTPRedirect 

func (s *ChallSrv) GetHTTPRedirect(path string) (string, bool)

GetHTTPRedirect returns the redirect target for the given path (if it exists) and a true bool. If the path does not have a redirect target 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) RequestHistory added in v1.0.1 

func (s *ChallSrv) RequestHistory(hostname string, typ RequestEventType) []RequestEvent

RequestHistory returns the server's request history for the given hostname and event type.

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) SetDefaultDNSIPv4 

func (s *ChallSrv) SetDefaultDNSIPv4(addr string)

SetDefaultDNSIPv4 sets the default IPv4 address used for A query responses that don't match hosts added with AddDNSARecord. Use "" to disable default A query responses.

func (*ChallSrv) SetDefaultDNSIPv6 

func (s *ChallSrv) SetDefaultDNSIPv6(addr string)

SetDefaultDNSIPv6 sets the default IPv6 address used for AAAA query responses that don't match hosts added with AddDNSAAAARecord. Use "" to disable default AAAA query responses.

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
	// HTTPSOneAddrs are the HTTPS HTTP-01 challenge server bind addresses/ports
	HTTPSOneAddrs []string
	// DOHAddrs are the DOH challenge server bind addresses/ports
	DOHAddrs []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

	// DOHCert is required if DOHAddrs is nonempty.
	DOHCert string
	// DOHCertKey is required if DOHAddrs is nonempty.
	DOHCertKey string
}

Config holds challenge server configuration

type DNSRequestEvent added in v1.0.1 

type DNSRequestEvent struct {
	// The DNS question received.
	Question dns.Question
}

DNSRequestEvent corresponds to a DNS request received by a dnsOneServer. It implements the RequestEvent interface.

func (DNSRequestEvent) Key added in v1.0.1 

func (e DNSRequestEvent) Key() string

DNSRequestEvents use the Question Name as the storage key. Any trailing `.` in the question name is removed.

func (DNSRequestEvent) Type added in v1.0.1 

func (e DNSRequestEvent) Type() RequestEventType

DNSRequestEvents always have type DNSRequestEventType

type HTTPRequestEvent added in v1.0.1 

type HTTPRequestEvent struct {
	// The full request URL (path and query arguments)
	URL string
	// The Host header from the request
	Host string
	// Whether the request was received over HTTPS or HTTP
	HTTPS bool
	// The ServerName from the ClientHello. May be empty if there was no SNI or if
	// the request was not HTTPS
	ServerName string
}

HTTPRequestEvent corresponds to an HTTP request received by a httpOneServer. It implements the RequestEvent interface.

func (HTTPRequestEvent) Key added in v1.0.1 

func (e HTTPRequestEvent) Key() string

HTTPRequestEvents use the HTTP Host as the storage key. Any explicit port will be removed.

func (HTTPRequestEvent) Type added in v1.0.1 

func (e HTTPRequestEvent) Type() RequestEventType

HTTPRequestEvents always have type HTTPRequestEventType

type MockCAAPolicy 

type MockCAAPolicy struct {
	Tag   string
	Value string
}

MockCAAPolicy holds a tag and a value for a CAA record. See https://tools.ietf.org/html/rfc6844

type RequestEvent added in v1.0.1 

type RequestEvent interface {
	Type() RequestEventType
	Key() string
}

A RequestEvent is anything that can identify its RequestEventType and a key for storing the request event in the history.

type RequestEventType added in v1.0.1 

type RequestEventType int

RequestEventType indicates what type of event occurred. 

const (
	// HTTP requests
	HTTPRequestEventType RequestEventType = iota
	// DNS requests
	DNSRequestEventType
	// TLS-ALPN-01 requests
	TLSALPNRequestEventType
)

type TLSALPNRequestEvent added in v1.0.1 

type TLSALPNRequestEvent struct {
	// ServerName from the TLS Client Hello.
	ServerName string
	// SupportedProtos from the TLS Client Hello.
	SupportedProtos []string
}

TLSALPNRequestEvent corresponds to a TLS request received by a tlsALPNOneServer. It implements the RequestEvent interface.

func (TLSALPNRequestEvent) Key added in v1.0.1 

func (e TLSALPNRequestEvent) Key() string

TLSALPNRequestEvents use the SNI value as the storage key

func (TLSALPNRequestEvent) Type added in v1.0.1 

func (e TLSALPNRequestEvent) Type() RequestEventType

TLSALPNRequestEvents always have type TLSALPNRequestEventType

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.