Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
203 changes: 129 additions & 74 deletions http/client_ip.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,6 @@ package http

import (
"context"
"net"
"net/http"
"net/netip"
"slices"
Expand Down Expand Up @@ -32,6 +31,10 @@ func ClientIPFromContext(ctx context.Context) (string, bool) {
// It checks X-Forwarded-For and X-Real-IP headers first (for proxied requests),
// then falls back to RemoteAddr.
//
// It is suitable for display and logging only. For a rate-limit key, access
// control or any other trust decision use ClientIPResolver.ClientAddr, which
// ignores these headers unless the peer is a configured trusted proxy.
//
// X-Forwarded-For, Forwarded, and X-Real-IP are ordinary request headers:
// any client can set them to an arbitrary value, and this function trusts
// them unconditionally with no allowlist of known proxy addresses. Unless
Expand Down Expand Up @@ -103,24 +106,27 @@ func parseForwardedHeader(f string) string {
return ""
}

// ClientIPResolver resolves a request's client IP address under an
// explicit trust model, unlike the package-level GetClientIP, which trusts
// forwarding headers unconditionally (see its doc comment). Zero or one
// trust mode may be configured:
// ClientIPResolver resolves a request's client address under an explicit
// trust model, unlike the package-level GetClientIP, which trusts forwarding
// headers unconditionally (see its doc comment). Zero or one trust mode may
// be configured:
//
// - WithTrustedHeader trusts one named header verbatim, for platforms
// whose edge sets a header this process can only receive by going
// through that edge (e.g. fly.io's Fly-Client-IP -- see
// NewFlyClientIPResolver).
// - WithTrustedProxyCIDRs walks X-Forwarded-For from the right against a
// caller-supplied set of trusted proxy ranges, for platforms that
// publish stable ranges (AWS ALB, Azure Application Gateway,
// Cloudflare, self-hosted nginx, etc).
// - WithTrustedProxyCIDRs walks X-Forwarded-For, or failing that
// Forwarded, from the right against a caller-supplied set of trusted
// proxy ranges, for platforms that publish stable ranges (AWS ALB,
// Azure Application Gateway, Cloudflare, self-hosted nginx, etc).
//
// If both are configured, WithTrustedHeader takes precedence. If neither is
// configured, ClientAddr is the request's direct peer address (RemoteAddr)
// only -- it never trusts a client-supplied header, unlike GetClientIP.
//
// If both are configured, WithTrustedHeader takes precedence. If neither
// is configured, ClientIP falls back to the request's direct peer address
// (RemoteAddr) only -- it never trusts a client-supplied header, unlike
// GetClientIP.
// When the listener understands the PROXY protocol (see WithProxyProtocol),
// RemoteAddr is already the real client, so the zero-configuration resolver
// is the right choice behind such a proxy.
type ClientIPResolver struct {
trustedHeader string
trustedProxyCIDRs []netip.Prefix
Expand All @@ -137,13 +143,16 @@ func WithTrustedHeader(name string) ClientIPResolverOption {
return func(c *ClientIPResolver) { c.trustedHeader = name }
}

// WithTrustedProxyCIDRs configures the resolver to walk X-Forwarded-For
// from the right, skipping entries whose address falls within the given
// CIDR ranges, and returning the first entry that doesn't -- the RFC
// 7239-style trusted-proxy-list algorithm. The request's direct peer
// (RemoteAddr) must also fall within the trusted set for X-Forwarded-For
// to be consulted at all; otherwise the peer is untrusted and is used
// directly, since any header it presents is unverified.
// WithTrustedProxyCIDRs configures the resolver to walk X-Forwarded-For (or
// Forwarded, when that is absent) from the right, skipping entries whose
// address falls within the given CIDR ranges, and returning the first entry
// that doesn't -- the RFC 7239-style trusted-proxy-list algorithm. The
// request's direct peer (RemoteAddr) must also fall within the trusted set
// for the headers to be consulted at all; otherwise the peer is untrusted and
// is used directly, since any header it presents is unverified.
//
// An entry that cannot be parsed ends the walk: it was written by a hop this
// process cannot vouch for, so the nearest address before it is returned.
func WithTrustedProxyCIDRs(cidrs ...netip.Prefix) ClientIPResolverOption {
return func(c *ClientIPResolver) { c.trustedProxyCIDRs = append(c.trustedProxyCIDRs, cidrs...) }
}
Expand Down Expand Up @@ -172,54 +181,78 @@ func NewFlyClientIPResolver() *ClientIPResolver {
return NewClientIPResolver(WithTrustedHeader("Fly-Client-IP"))
}

// ClientIP resolves r's client IP under the configured trust mode.
func (c *ClientIPResolver) ClientIP(r *http.Request) string {
// ClientAddr resolves r's client address under the configured trust mode. It
// returns the zero Addr when neither the headers nor RemoteAddr yield a valid
// address. IPv4-mapped IPv6 addresses are returned as IPv4 and zones are
// dropped, so the result is a stable key.
func (c *ClientIPResolver) ClientAddr(r *http.Request) netip.Addr {
if c.trustedHeader != "" {
return c.clientIPFromTrustedHeader(r)
return c.clientAddrFromTrustedHeader(r)
}
if len(c.trustedProxyCIDRs) > 0 {
return c.clientIPFromTrustedProxyCIDRs(r)
return c.clientAddrFromTrustedProxyCIDRs(r)
}

return c.remoteAddrString(r)
return remoteAddrIP(r)
}

// ClientIP resolves r's client address as a string, falling back to the raw
// RemoteAddr when it cannot be parsed.
//
// Deprecated: Use ClientAddr, which returns a netip.Addr.
func (c *ClientIPResolver) ClientIP(r *http.Request) string {
return c.clientAddrString(r)
}

// PrincipalFunc adapts ClientIP to the PrincipalFunc signature, for use
// PrincipalFunc adapts ClientAddr to the PrincipalFunc signature, for use
// with WithRateLimiterPrincipalFunc/WithPrincipalFunc.
func (c *ClientIPResolver) PrincipalFunc(r *http.Request) (string, error) {
return c.ClientIP(r), nil
return c.clientAddrString(r), nil
}

func (c *ClientIPResolver) clientIPFromTrustedHeader(r *http.Request) string {
if v := strings.TrimSpace(r.Header.Get(c.trustedHeader)); v != "" {
return v
func (c *ClientIPResolver) clientAddrString(r *http.Request) string {
if addr := c.ClientAddr(r); addr.IsValid() {
return addr.String()
}
// The trusted header is unexpectedly absent (e.g. something hit this

return r.RemoteAddr
}

func (c *ClientIPResolver) clientAddrFromTrustedHeader(r *http.Request) netip.Addr {
if addr, ok := parseForwardedIP(r.Header.Get(c.trustedHeader)); ok {
return addr
}
// The trusted header is absent or unusable (e.g. something hit this
// process directly, bypassing the edge that normally sets it).
return c.remoteAddrString(r)
return remoteAddrIP(r)
}

func (c *ClientIPResolver) clientIPFromTrustedProxyCIDRs(r *http.Request) string {
peer, ok := remoteAddrIP(r)
if !ok || !c.isTrustedProxy(peer) {
func (c *ClientIPResolver) clientAddrFromTrustedProxyCIDRs(r *http.Request) netip.Addr {
peer := remoteAddrIP(r)
if !peer.IsValid() || !c.isTrustedProxy(peer) {
// The immediate peer isn't a trusted proxy (or couldn't be
// parsed), so any X-Forwarded-For it presents is unverified --
// the peer itself is the only address that can be trusted.
return c.remoteAddrString(r)
// parsed), so any header it presents is unverified -- the peer
// itself is the only address that can be trusted.
return peer
}

for entry := range reverseSplitSeq(r.Header.Get("X-Forwarded-For"), ",") {
addr, ok := parseForwardedIP(entry)
hops := forwardedHops(r)

// nearest is the closest hop already known to be a trusted proxy.
nearest := peer
for _, hop := range slices.Backward(hops) {
addr, ok := parseForwardedIP(hop)
if !ok {
continue
return nearest
}
if !c.isTrustedProxy(addr) {
return addr.String()
return addr
}
nearest = addr
}

// Every entry (or none at all) was a trusted proxy; fall back to the peer.
return peer.String()
// Every entry (or none at all) was a trusted proxy.
return peer
}

func (c *ClientIPResolver) isTrustedProxy(addr netip.Addr) bool {
Expand All @@ -232,50 +265,72 @@ func (c *ClientIPResolver) isTrustedProxy(addr netip.Addr) bool {
return false
}

// remoteAddrString returns r.RemoteAddr's IP, or the raw RemoteAddr if it
// can't be parsed.
func (c *ClientIPResolver) remoteAddrString(r *http.Request) string {
if peer, ok := remoteAddrIP(r); ok {
return peer.String()
// forwardedHops returns the hop addresses from X-Forwarded-For, or failing
// that the for= values of Forwarded, in the order the proxies appended them.
func forwardedHops(r *http.Request) []string {
if xff := r.Header.Values("X-Forwarded-For"); len(xff) > 0 {
return splitHeaderList(xff)
}

return r.RemoteAddr
var hops []string
for _, h := range splitHeaderList(r.Header.Values("Forwarded")) {
hops = append(hops, forwardedFor(h))
}

return hops
}

// remoteAddrIP extracts and parses the IP portion of r.RemoteAddr, which
// net/http guarantees to be in "IP:port" form.
func remoteAddrIP(r *http.Request) (netip.Addr, bool) {
host, _, err := net.SplitHostPort(r.RemoteAddr)
if err != nil {
host = r.RemoteAddr
// splitHeaderList splits repeated, comma-separated header values into
// elements, in order.
func splitHeaderList(values []string) []string {
out := make([]string, 0, len(values))
for _, v := range values {
out = append(out, strings.Split(v, ",")...)
}
addr, err := netip.ParseAddr(host)

return addr, err == nil
return out
}

// parseForwardedIP parses a single X-Forwarded-For entry, tolerating
// surrounding whitespace and bracketed IPv6 literals.
// forwardedFor returns the for= value of one Forwarded element, or "" when it
// has none.
func forwardedFor(element string) string {
for part := range strings.SplitSeq(element, ";") {
before, after, ok := strings.Cut(strings.TrimSpace(part), "=")
if ok && strings.EqualFold(before, "for") {
return strings.Trim(strings.TrimSpace(after), "\"")
}
}

return ""
}

// remoteAddrIP extracts and parses the IP portion of r.RemoteAddr, which
// net/http guarantees to be in "IP:port" form. It returns the zero Addr when
// that cannot be parsed.
func remoteAddrIP(r *http.Request) netip.Addr {
addr, _ := parseForwardedIP(r.RemoteAddr)

return addr
}

// parseForwardedIP parses a single address as it appears in a forwarding
// header or RemoteAddr, tolerating surrounding whitespace, an optional port
// and bracketed IPv6 literals. The result is unmapped and has no zone.
func parseForwardedIP(s string) (netip.Addr, bool) {
s = strings.TrimSpace(s)
if ap, err := netip.ParseAddrPort(s); err == nil {
return normaliseAddr(ap.Addr()), true
}
s = strings.TrimPrefix(s, "[")
s = strings.TrimSuffix(s, "]")
addr, err := netip.ParseAddr(s)
if err != nil {
return netip.Addr{}, false
}

return addr, err == nil
return normaliseAddr(addr), true
}

// reverseSplitSeq splits s on sep and yields the parts from right to left.
func reverseSplitSeq(s, sep string) func(yield func(string) bool) {
return func(yield func(string) bool) {
if s == "" {
return
}
parts := strings.Split(s, sep)
for _, part := range slices.Backward(parts) {
if !yield(part) {
return
}
}
}
func normaliseAddr(addr netip.Addr) netip.Addr {
return addr.Unmap().WithZone("")
}
58 changes: 58 additions & 0 deletions http/client_ip_config.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
package http

import (
"net/netip"

"github.com/dioad/config/configcheck"
)

// ClientIPConfig is the trust model of ClientIPResolver, in the form services
// take it in their configuration. An empty config trusts no header, so the
// client address is the connection's address.
type ClientIPConfig struct {
// TrustedProxies are the ranges of the proxies in front of the service,
// in CIDR notation. Forwarding headers are honoured only from a peer in
// one of them.
TrustedProxies []string `desc:"CIDR ranges of proxies whose forwarding headers are trusted" mapstructure:"trusted-proxies"`

// TrustedHeader names a header set by an edge that this process can only
// be reached through, such as Fly-Client-IP on fly.io. It takes
// precedence over TrustedProxies.
TrustedHeader string `desc:"header set by the edge proxy that is trusted verbatim" mapstructure:"trusted-header"`
}

// Check reports to c a trusted proxy that is not a CIDR range, and trust
// modes set together. c is positioned at the config's own block.
func (c ClientIPConfig) Check(findings *configcheck.Collector) {
for i, p := range c.TrustedProxies {
if _, err := netip.ParsePrefix(p); err != nil {
findings.Field("trusted-proxies").Index(i).Errorf("%q is not a CIDR range: %v", p, err)
}
}
if c.TrustedHeader != "" && len(c.TrustedProxies) > 0 {
findings.Field("trusted-header").Errorf("is set together with trusted-proxies, which it takes precedence over; set only one")
}
}

// Resolver returns the ClientIPResolver for c. It returns an error for a
// trusted proxy that is not a CIDR range; Check reports the same.
func (c ClientIPConfig) Resolver() (*ClientIPResolver, error) {
var opts []ClientIPResolverOption
if c.TrustedHeader != "" {
opts = append(opts, WithTrustedHeader(c.TrustedHeader))
}

prefixes := make([]netip.Prefix, 0, len(c.TrustedProxies))
for _, p := range c.TrustedProxies {
prefix, err := netip.ParsePrefix(p)
if err != nil {
return nil, err
}
prefixes = append(prefixes, prefix)
}
if len(prefixes) > 0 {
opts = append(opts, WithTrustedProxyCIDRs(prefixes...))
}

return NewClientIPResolver(opts...), nil
}
Loading
Loading