You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tailscale/safeweb/http.go

344 lines
13 KiB
Go

// Copyright (c) Tailscale Inc & AUTHORS
// SPDX-License-Identifier: BSD-3-Clause
// Package safeweb provides a wrapper around an http.Server that applies
// basic web application security defenses by default. The wrapper can be
// used in place of an http.Server. A safeweb.Server adds mitigations for
// Cross-Site Request Forgery (CSRF) attacks, and annotates requests with
// appropriate Cross-Origin Resource Sharing (CORS), Content-Security-Policy,
// X-Content-Type-Options, and Referer-Policy headers.
//
// To use safeweb, the application must separate its "browser" routes from "API"
// routes, with each on its own http.ServeMux. When serving requests, the
// server will first check the browser mux, and if no matching route is found it
// will defer to the API mux.
//
// # Browser Routes
//
// All routes in the browser mux enforce CSRF protection using the gorilla/csrf
// package. The application must template the CSRF token into its forms using
// the [TemplateField] and [TemplateTag] APIs. Applications that are served in a
// secure context (over HTTPS) should also set the SecureContext field to true
// to ensure that the the CSRF cookies are marked as Secure.
//
// In addition, browser routes will also have the following applied:
// - Content-Security-Policy header that disallows inline scripts, framing, and third party resources.
// - X-Content-Type-Options header on responses set to "nosniff" to prevent MIME type sniffing attacks.
// - Referer-Policy header set to "same-origin" to prevent leaking referrer information to third parties.
//
// By default the Content-Security-Policy header will disallow inline styles.
// This can be overridden by setting the CSPAllowInlineStyles field to true in
// the safeweb.Config struct.
//
// # API routes
//
// safeweb inspects the Content-Type header of incoming requests to the API mux
// and prohibits the use of `application/x-www-form-urlencoded` values. If the
// application provides a list of allowed origins and methods in its
// configuration safeweb will set the appropriate CORS headers on pre-flight
// OPTIONS requests served by the API mux.
//
// # HTTP Redirects
//
// The [RedirectHTTP] method returns a handler that redirects all incoming HTTP
// requests to HTTPS at the same path on the provided fully qualified domain
// name (FQDN).
//
// # Example usage
//
// h := http.NewServeMux()
// h.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
// fmt.Fprint(w, "Hello, world!")
// })
// s, err := safeweb.NewServer(safeweb.Config{
// BrowserMux: h,
// })
// if err != nil {
// log.Fatalf("failed to create server: %v", err)
// }
// ln, err := net.Listen("tcp", ":8080")
// if err != nil {
// log.Fatalf("failed to listen: %v", err)
// }
// defer ln.Close()
// if err := s.Serve(ln); err != nil && err != http.ErrServerClosed {
// log.Fatalf("failed to serve: %v", err)
// }
//
// [TemplateField]: https://pkg.go.dev/github.com/gorilla/csrf#TemplateField
// [TemplateTag]: https://pkg.go.dev/github.com/gorilla/csrf#TemplateTag
package safeweb
import (
"cmp"
crand "crypto/rand"
"fmt"
"log"
"net"
"net/http"
"net/url"
"path"
"strings"
"github.com/gorilla/csrf"
)
// The default Content-Security-Policy header.
var defaultCSP = strings.Join([]string{
`default-src 'self'`, // origin is the only valid source for all content types
`script-src 'self'`, // disallow inline javascript
`frame-ancestors 'none'`, // disallow framing of the page
`form-action 'self'`, // disallow form submissions to other origins
`base-uri 'self'`, // disallow base URIs from other origins
`block-all-mixed-content`, // disallow mixed content when serving over HTTPS
`object-src 'self'`, // disallow embedding of resources from other origins
}, "; ")
// The default Strict-Transport-Security header. This header tells the browser
// to exclusively use HTTPS for all requests to the origin for the next year.
var DefaultStrictTransportSecurityOptions = "max-age=31536000"
// Config contains the configuration for a safeweb server.
type Config struct {
// SecureContext specifies whether the Server is running in a secure (HTTPS) context.
// Setting this to true will cause the Server to set the Secure flag on CSRF cookies.
SecureContext bool
// BrowserMux is the HTTP handler for any routes in your application that
// should only be served to browsers in a primary origin context. These
// requests will be subject to CSRF protection and will have
// browser-specific headers in their responses.
BrowserMux *http.ServeMux
// APIMux is the HTTP handler for any routes in your application that
// should only be served to non-browser clients or to browsers in a
// cross-origin resource sharing context.
APIMux *http.ServeMux
// AccessControlAllowOrigin specifies the Access-Control-Allow-Origin header sent in response to pre-flight OPTIONS requests.
// Provide a list of origins, e.g. ["https://foobar.com", "https://foobar.net"] or the wildcard value ["*"].
// No headers will be sent if no origins are provided.
AccessControlAllowOrigin []string
// AccessControlAllowMethods specifies the Access-Control-Allow-Methods header sent in response to pre-flight OPTIONS requests.
// Provide a list of methods, e.g. ["GET", "POST", "PUT", "DELETE"].
// No headers will be sent if no methods are provided.
AccessControlAllowMethods []string
// CSRFSecret is the secret used to sign CSRF tokens. It must be 32 bytes long.
// This should be considered a sensitive value and should be kept secret.
// If this is not provided, the Server will generate a random CSRF secret on
// startup.
CSRFSecret []byte
// CSPAllowInlineStyles specifies whether to include `style-src:
// unsafe-inline` in the Content-Security-Policy header to permit the use of
// inline CSS.
CSPAllowInlineStyles bool
// CookiesSameSiteLax specifies whether to use SameSite=Lax in cookies. The
// default is to set SameSite=Strict.
CookiesSameSiteLax bool
// StrictTransportSecurityOptions specifies optional directives for the
// Strict-Transport-Security header sent in response to requests made to the
// BrowserMux when SecureContext is true.
// If empty, it defaults to max-age of 1 year.
StrictTransportSecurityOptions string
// HTTPServer, if specified, is the underlying http.Server that safeweb will
// use to serve requests. If nil, a new http.Server will be created.
// Do not use the Handler field of http.Server, as it will be ignored.
// Instead, set your handlers using APIMux and BrowserMux.
HTTPServer *http.Server
}
func (c *Config) setDefaults() error {
if c.BrowserMux == nil {
c.BrowserMux = &http.ServeMux{}
}
if c.APIMux == nil {
c.APIMux = &http.ServeMux{}
}
if c.CSRFSecret == nil || len(c.CSRFSecret) == 0 {
c.CSRFSecret = make([]byte, 32)
if _, err := crand.Read(c.CSRFSecret); err != nil {
return fmt.Errorf("failed to generate CSRF secret: %w", err)
}
}
return nil
}
// Server is a safeweb server.
type Server struct {
Config
h *http.Server
csp string
csrfProtect func(http.Handler) http.Handler
}
// NewServer creates a safeweb server with the provided configuration. It will
// validate the configuration to ensure that it is complete and return an error
// if not.
func NewServer(config Config) (*Server, error) {
// ensure that CORS configuration is complete
corsMethods := len(config.AccessControlAllowMethods) > 0
corsHosts := len(config.AccessControlAllowOrigin) > 0
if corsMethods != corsHosts {
return nil, fmt.Errorf("must provide both AccessControlAllowOrigin and AccessControlAllowMethods or neither")
}
// fill in any missing fields
if err := config.setDefaults(); err != nil {
return nil, fmt.Errorf("failed to set defaults: %w", err)
}
sameSite := csrf.SameSiteStrictMode
if config.CookiesSameSiteLax {
sameSite = csrf.SameSiteLaxMode
}
s := &Server{
Config: config,
csp: defaultCSP,
// only set Secure flag on CSRF cookies if we are in a secure context
// as otherwise the browser will reject the cookie
csrfProtect: csrf.Protect(config.CSRFSecret, csrf.Secure(config.SecureContext), csrf.SameSite(sameSite)),
}
if config.CSPAllowInlineStyles {
s.csp = defaultCSP + `; style-src 'self' 'unsafe-inline'`
}
s.h = cmp.Or(config.HTTPServer, &http.Server{})
if s.h.Handler != nil {
return nil, fmt.Errorf("use safeweb.Config.APIMux and safeweb.Config.BrowserMux instead of http.Server.Handler")
}
s.h.Handler = s
return s, nil
}
type handlerType int
const (
unknownHandler handlerType = iota
apiHandler
browserHandler
)
// checkHandlerType returns either apiHandler or browserHandler, depending on
// whether apiPattern or browserPattern is more specific (i.e. which pattern
// contains more pathname components). If they are equally specific, it returns
// unknownHandler.
func checkHandlerType(apiPattern, browserPattern string) handlerType {
c := cmp.Compare(strings.Count(path.Clean(apiPattern), "/"), strings.Count(path.Clean(browserPattern), "/"))
switch {
case c > 0:
return apiHandler
case c < 0:
return browserHandler
default:
return unknownHandler
}
}
func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) {
_, bp := s.BrowserMux.Handler(r)
_, ap := s.APIMux.Handler(r)
switch {
case bp == "" && ap != "": // APIMux match
s.serveAPI(w, r)
case bp != "" && ap == "": // BrowserMux match
s.serveBrowser(w, r)
case bp == "" && ap == "": // neither match
http.NotFound(w, r)
case bp != "" && ap != "":
// Both muxes match the path. Route to the more-specific handler (as
// determined by the number of components in the path). If it somehow
// happens that both patterns are equally specific, something strange
// has happened; say so.
//
// NOTE: checkHandlerType does not know about what the serve* handlers
// will do — including, possibly, redirecting to more specific patterns.
// If you have a less-specific pattern that redirects to something more
// specific, this logic will not do what you wanted.
handler := checkHandlerType(ap, bp)
switch handler {
case apiHandler:
s.serveAPI(w, r)
case browserHandler:
s.serveBrowser(w, r)
default:
s := http.StatusInternalServerError
log.Printf("conflicting mux paths in safeweb: request %q matches browser mux pattern %q and API mux pattern %q; returning %d", r.URL.Path, bp, ap, s)
http.Error(w, "multiple handlers match this request", s)
}
}
}
func (s *Server) serveAPI(w http.ResponseWriter, r *http.Request) {
// disallow x-www-form-urlencoded requests to the API
if r.Header.Get("Content-Type") == "application/x-www-form-urlencoded" {
http.Error(w, "invalid content type", http.StatusBadRequest)
return
}
// set CORS headers for pre-flight OPTIONS requests if any were configured
if r.Method == "OPTIONS" && len(s.AccessControlAllowOrigin) > 0 {
w.Header().Set("Access-Control-Allow-Origin", strings.Join(s.AccessControlAllowOrigin, ", "))
w.Header().Set("Access-Control-Allow-Methods", strings.Join(s.AccessControlAllowMethods, ", "))
}
s.APIMux.ServeHTTP(w, r)
}
func (s *Server) serveBrowser(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Security-Policy", s.csp)
w.Header().Set("X-Content-Type-Options", "nosniff")
w.Header().Set("Referer-Policy", "same-origin")
if s.SecureContext {
w.Header().Set("Strict-Transport-Security", cmp.Or(s.StrictTransportSecurityOptions, DefaultStrictTransportSecurityOptions))
}
s.csrfProtect(s.BrowserMux).ServeHTTP(w, r)
}
// ServeRedirectHTTP serves a single HTTP handler on the provided listener that
// redirects all incoming HTTP requests to the HTTPS address of the provided
// fully qualified domain name (FQDN). Callers are responsible for closing the
// listener.
func (s *Server) ServeRedirectHTTP(ln net.Listener, fqdn string) error {
return http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
new := url.URL{
Scheme: "https",
Host: fqdn,
Path: r.URL.Path,
RawQuery: r.URL.RawQuery,
}
http.Redirect(w, r, new.String(), http.StatusMovedPermanently)
}))
}
// Serve starts the server and listens on the provided listener. It will block
// until the server is closed. The caller is responsible for closing the
// listener.
func (s *Server) Serve(ln net.Listener) error {
return s.h.Serve(ln)
}
// ListenAndServe listens on the TCP network address addr and then calls Serve
// to handle requests on incoming connections. If addr == "", ":http" is used.
func (s *Server) ListenAndServe(addr string) error {
if addr == "" {
addr = ":http"
}
lst, err := net.Listen("tcp", addr)
if err != nil {
return err
}
return s.Serve(lst)
}
// Close closes all client connections and stops accepting new ones.
func (s *Server) Close() error {
return s.h.Close()
}