Documentation
¶
Overview ¶
Package reverseproxy provides reverse proxy functionality with automatic TLS via ACME.
Index ¶
Constants ¶
const ( HeaderClientCertSubject = "X-Client-Cert-Subject" HeaderClientCertIssuer = "X-Client-Cert-Issuer" HeaderClientCertCN = "X-Client-Cert-CN" HeaderClientCertSerial = "X-Client-Cert-Serial" )
Headers carrying the verified client certificate identity to backends.
Variables ¶
var ClientAuthModes = []ClientAuthMode{ ClientAuthNone, ClientAuthRequest, ClientAuthRequireAny, ClientAuthVerifyIfGiven, ClientAuthRequireAndVerify, }
ClientAuthModes lists every supported mode, in increasing order of strictness.
Functions ¶
This section is empty.
Types ¶
type Backend ¶
type Backend struct {
// Host is the hostname/pattern to match (e.g., "api.example.com" or "*.example.com")
Host string `yaml:"host"`
// Target is the backend URL (e.g., "http://localhost:3000")
Target string `yaml:"target"`
// StripPrefix removes a path prefix before forwarding
StripPrefix string `yaml:"stripPrefix,omitempty"`
// AddHeaders are headers to add to proxied requests
AddHeaders map[string]string `yaml:"addHeaders,omitempty"`
// HealthCheck is the health check path
HealthCheck string `yaml:"healthCheck,omitempty"`
// TLS configures the client presented to an HTTPS backend that requires mutual TLS.
TLS *BackendTLS `yaml:"tls,omitempty"`
}
Backend represents a backend server configuration.
type BackendTLS ¶ added in v0.2.0
type BackendTLS struct {
// CertFile is the PEM client certificate to present to the backend.
CertFile string `yaml:"certFile,omitempty"`
// KeyFile is the PEM private key for CertFile. If empty, the key is read from CertFile.
KeyFile string `yaml:"keyFile,omitempty"`
// CAFile is a PEM bundle of CAs used to verify the backend server certificate. If empty,
// the system trust store is used.
CAFile string `yaml:"caFile,omitempty"`
// InsecureSkipVerify disables verification of the backend server certificate. It exists
// for self-signed backends in development and must not be used in production.
InsecureSkipVerify bool `yaml:"insecureSkipVerify,omitempty"`
}
BackendTLS configures the TLS client used to connect to an HTTPS backend, including a client certificate to present when the backend itself requires mutual TLS. It is the mirror of the frontend ClientCAPaths/ClientAuth options: those verify certificates presented by callers, these present a certificate to upstream servers.
type ClientAuthMode ¶ added in v0.2.0
type ClientAuthMode string
ClientAuthMode controls how client certificates are requested and verified during the TLS handshake (mutual TLS).
const ( // ClientAuthNone disables client certificate authentication. ClientAuthNone ClientAuthMode = "none" // ClientAuthRequest asks for a client certificate but neither requires nor verifies it. ClientAuthRequest ClientAuthMode = "request" // ClientAuthRequireAny requires a client certificate but does not verify it against the CA pool. ClientAuthRequireAny ClientAuthMode = "require-any" // ClientAuthVerifyIfGiven verifies a client certificate against the CA pool, but allows // connections that offer none. ClientAuthVerifyIfGiven ClientAuthMode = "verify-if-given" // ClientAuthRequireAndVerify requires a client certificate and verifies it against the // CA pool. This is the usual mTLS posture. ClientAuthRequireAndVerify ClientAuthMode = "require-and-verify" )
func (ClientAuthMode) Enabled ¶ added in v0.2.0
func (m ClientAuthMode) Enabled() bool
Enabled reports whether the mode requests a client certificate at all.
func (ClientAuthMode) RequiresCAPool ¶ added in v0.2.0
func (m ClientAuthMode) RequiresCAPool() bool
RequiresCAPool reports whether the mode verifies client certificates against a CA pool, and therefore needs at least one client CA to be configured.
func (ClientAuthMode) TLSClientAuthType ¶ added in v0.2.0
func (m ClientAuthMode) TLSClientAuthType() (tls.ClientAuthType, error)
TLSClientAuthType maps the mode onto its crypto/tls equivalent.
type Config ¶
type Config struct {
// HTTPPort is the port for HTTP traffic (default: 80)
HTTPPort int
// HTTPSPort is the port for HTTPS traffic (default: 443)
HTTPSPort int
// Backends is the list of backend configurations
Backends []Backend
// ACMEEmail is the email for Let's Encrypt registration
ACMEEmail string
// ACMECacheDir is the directory to cache certificates
ACMECacheDir string
// ACMEStaging uses Let's Encrypt staging environment (for testing)
ACMEStaging bool
// Capturer is the traffic capturer (optional)
Capturer *capture.Capturer
// Verbose enables verbose logging
Verbose bool
// RedirectHTTP redirects HTTP to HTTPS
RedirectHTTP bool
// ClientCAPaths are PEM files holding the CAs used to verify client certificates (mTLS).
ClientCAPaths []string
// ClientAuth controls client certificate verification. It defaults to
// ClientAuthRequireAndVerify when ClientCAPaths is non-empty, and ClientAuthNone otherwise.
ClientAuth ClientAuthMode
// Middleware optionally wraps the request-serving handler, e.g. for telemetry. It is
// applied on the HTTPS listener, and on the HTTP listener when RedirectHTTP is false.
Middleware func(http.Handler) http.Handler
}
Config holds reverse proxy configuration.
func DefaultConfig ¶
func DefaultConfig() *Config
DefaultConfig returns default reverse proxy configuration.
type ReverseProxy ¶
type ReverseProxy struct {
// contains filtered or unexported fields
}
ReverseProxy represents a reverse proxy server with ACME support.
func New ¶
func New(cfg *Config) (*ReverseProxy, error)
New creates a new reverse proxy with the given configuration.
func (*ReverseProxy) ClientAuthMode ¶ added in v0.2.0
func (rp *ReverseProxy) ClientAuthMode() ClientAuthMode
ClientAuthMode returns the resolved client certificate authentication mode.
func (*ReverseProxy) HealthCheck ¶
func (rp *ReverseProxy) HealthCheck(ctx context.Context) map[string]bool
HealthCheck performs health checks on all backends.
func (*ReverseProxy) ListenAndServe ¶
func (rp *ReverseProxy) ListenAndServe() error
ListenAndServe starts the reverse proxy server.
func (*ReverseProxy) ServeHTTP ¶
func (rp *ReverseProxy) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP implements the http.Handler interface.
func (*ReverseProxy) TLSConfig ¶
func (rp *ReverseProxy) TLSConfig() *tls.Config
TLSConfig returns the TLS configuration with ACME support, including client certificate verification (mTLS) when configured.