Documentation
¶
Overview ¶
Package ipaccess allows or blocks requests by the client's IP address, given as literals, CIDR blocks or ranges.
The address is the one Context.RemoteAddr returns: the address of the connection or, when Options.Context.RemoteAddrHeaders is set, the one a proxy wrote in such a header. See the SECURITY WARNING on New.
Its entry point is New(allowed, blocked []string) (Handler, error), which reports a malformed pattern; Must(allowed, blocked) is the panicking companion.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Must ¶
Must is New for a caller that has nothing to do with a malformed pattern: it panics instead of reporting one, so a registration stays a single expression.
app.Use(ipaccess.Must([]string{"127.0.0.1", "10.0.0.0/8"}, nil))
The patterns are usually literals or configuration read at startup, and a bad one there is a broken deployment rather than a request-time failure. Use New when they come from somewhere that can be wrong at run time.
func New ¶
New returns a middleware that allows or blocks requests by client IP address.
An empty "allowedPatterns" means "allow everything that is not blocked"; a non-empty one means "allow only these".
The client IP comes from Context.RemoteAddr. With no Options.Context.RemoteAddrHeaders it is the address of the connection. With one, the header is read from the right, where a proxy appends the address it got the request from: the first public address is the client IP, and when no header gives one it is the address of the connection.
SECURITY WARNING: Iris has no trusted-proxy list yet, so with RemoteAddrHeaders set the client IP is only as good as the proxy in front of the application:
- A client that reaches the server directly, with no proxy in front, writes the whole header and with it the client IP. Such a server MUST be reachable through the proxy only.
- A header that the proxy passes on as the client sent it is the client's. Name only headers the proxy writes: a header is read when the ones named before it give no public address.
- A client inside your network is appended as a private address, which is skipped as one of your own proxies: the entry on its left is read, and the client wrote that one. A proxy that OVERWRITES the header closes this.
- A private address in the header is never the client IP, so a pattern such as "10.0.0.0/8" does not match a client that an internal proxy reports as 10.0.0.5: the address of the connection, the proxy, is matched. RemoteAddrHeadersForce takes the first address of a header that has no public one, which the client can write, and an empty RemoteAddrPrivateSubnets takes the right-most one, which the nearest proxy appended. A loopback address is skipped whatever that list holds, so only RemoteAddrHeadersForce takes it.
- A proxy with a public address in front of your own one, a CDN for example, is appended as a public address: it is the client IP, and the client it got the request from is not read. Add its range to RemoteAddrPrivateSubnets to have it skipped. That list is checked for IPv4 addresses only.
The client IP used to come from Context.Addr, which returns the FIRST entry of the header, so sending the header was enough to pass an allowlist or to escape a blocklist.
Types ¶
This section is empty.