README
¶
whitelist
This is a simple whitelisting package that encompasses several common patterns into a reusable package.
The basic type of a whitelist is the ACL type, which provides
a single method on a net.IP value:
Permitteddetermines whether the IP address is whitelisted and therefore should be permitted access. It should return true if the address is whitelisted.
Additionally, there are two other types that are built on the ACL
type; the HostACL stores individual hosts and the NetACL stores
networks. Each of these provides two functions that differ in the
types of their arguments.
Addwhitelists the IP address.Removedrops the IP address from the whitelist.
The HostACL operates on net.IP values, while the NetACL operates
on *net.IPNets.
There are currently four implementations of ACL provided in this
package; a basic implementation of the two types of ACLs and a stub
type for each:
Basicis a simple host-based whitelister that converts the IP addresses to strings; the whitelist is implemented as a set of string addresses. The set is implemented as amap[string]bool, and uses async.Mutexto coordinate updates to the whitelist.BasicNetis a simple network-based whitelister that similarly uses a mutex and an array to store networks. This has a number of limitations: operations are /O(n)/, and subsets/supersets of existing networks isn't detected. That is, if 192.168.3.0/24 is removed from a whitelist that has 192.168.0.0/16 permitted, that subnet will not actually be removed. Exact networks are required forAddandRemoveat this time.HostStubandNetStubare stand-in whitelists that always permits addresses. They are vocal about logging warning messages noting that whitelisting is stubbed. They are designed to be used in cases where whitelisting is desired, but the mechanics of whitelisting (i.e. administration of the whitelist) is not yet implemented, perhaps to keep whitelists in the system's flow.
Two convenience functions are provided here for extracting IP addresses:
NetConnLookupaccepts anet.Connvalue, and returns thenet.IPvalue from the connection.HTTPRequestLookupaccepts a*http.Requestand returns thenet.IPvalue from the request.
There are also two functions for whitelisting HTTP endpoints:
NewHandlerreturns anhttp.HandlerNewHandlerFuncreturns anhttp.HandlerFunc
These endpoints will work with both HostACL and NetACL.
Example http.Handler
This is a file server that uses a pair of whitelists. The admin whitelist permits modifications to the user whitelist only by the localhost. The user whitelist controls which hosts have access to the file server.
package main
import (
"encoding/json"
"flag"
"fmt"
"log"
"net"
"net/http"
"github.com/cloudflare/cfssl/whitelist"
)
var wl = whitelist.NewBasic()
func addIP(w http.ResponseWriter, r *http.Request) {
addr := r.FormValue("ip")
ip := net.ParseIP(addr)
wl.Add(ip)
log.Printf("request to add %s to the whitelist", addr)
w.Write([]byte(fmt.Sprintf("Added %s to whitelist.\n", addr)))
}
func delIP(w http.ResponseWriter, r *http.Request) {
addr := r.FormValue("ip")
ip := net.ParseIP(addr)
wl.Remove(ip)
log.Printf("request to remove %s from the whitelist", addr)
w.Write([]byte(fmt.Sprintf("Removed %s from whitelist.\n", ip)))
}
func dumpWhitelist(w http.ResponseWriter, r *http.Request) {
out, err := json.Marshal(wl)
if err != nil {
http.Error(w, err.Error(), http.StatusInternalServerError)
} else {
w.Write(out)
}
}
type handler struct {
h func(http.ResponseWriter, *http.Request)
}
func newHandler(h func(w http.ResponseWriter, r *http.Request)) http.Handler {
return &handler{h: h}
}
func (h *handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
h.h(w, r)
}
func main() {
root := flag.String("root", "files/", "file server root")
flag.Parse()
fileServer := http.StripPrefix("/files/",
http.FileServer(http.Dir(*root)))
wl.Add(net.IP{127, 0, 0, 1})
adminWL := whitelist.NewBasic()
adminWL.Add(net.IP{127, 0, 0, 1})
adminWL.Add(net.ParseIP("::1"))
protFiles, err := whitelist.NewHandler(fileServer, nil, wl)
if err != nil {
log.Fatalf("%v", err)
}
addHandler, err := whitelist.NewHandlerFunc(addIP, nil, adminWL)
if err != nil {
log.Fatalf("%v", err)
}
delHandler, err := whitelist.NewHandlerFunc(delIP, nil, adminWL)
if err != nil {
log.Fatalf("%v", err)
}
dumpHandler, err := whitelist.NewHandlerFunc(dumpWhitelist, nil, adminWL)
if err != nil {
log.Fatalf("%v", err)
}
http.Handle("/files/", protFiles)
http.Handle("/add", addHandler)
http.Handle("/del", delHandler)
http.Handle("/dump", dumpHandler)
log.Println("Serving files on :8080")
log.Fatal(http.ListenAndServe(":8080", nil))
}
Documentation
¶
Overview ¶
Package whitelist implements IP whitelisting for various types of connections. Two types of access control lists (ACLs) are supported: host-based and network-based.
Index ¶
- func DumpBasic(wl *Basic) []byte
- func HTTPRequestLookup(req *http.Request) (net.IP, error)
- func NetConnLookup(conn net.Conn) (net.IP, error)
- func NewHandler(allow, deny http.Handler, acl ACL) (http.Handler, error)
- type ACL
- type Basic
- type BasicNet
- type Handler
- type HandlerFunc
- type HostACL
- type HostStub
- type NetACL
- type NetStub
- Bugs
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HTTPRequestLookup ¶
HTTPRequestLookup extracts an IP from the remote address in a *http.Request. A single *http.Request should be passed to Address.
func NetConnLookup ¶
NetConnLookup extracts an IP from the remote address in the net.Conn. A single net.Conn should be passed to Address.
func NewHandler ¶
NewHandler returns a new whitelisting-wrapped HTTP handler. The allow handler should contain a handler that will be called if the request is whitelisted; the deny handler should contain a handler that will be called in the request is not whitelisted.
Types ¶
type ACL ¶
type ACL interface {
// Permitted takes an IP address, and returns true if the
// IP address is whitelisted (e.g. permitted access).
Permitted(net.IP) bool
}
An ACL stores a list of permitted IP addresses, and handles concurrency as needed.
type Basic ¶
type Basic struct {
// contains filtered or unexported fields
}
Basic implements a basic map-backed whitelister that uses an RWMutex for conccurency. IPv4 addresses are treated differently than an IPv6 address; namely, the IPv4 localhost will not match the IPv6 localhost.
func (*Basic) MarshalJSON ¶
MarshalJSON serialises a host whitelist to a comma-separated list of hosts, implementing the json.Marshaler interface.
func (*Basic) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface for host whitelists, taking a comma-separated string of hosts.
type BasicNet ¶
type BasicNet struct {
// contains filtered or unexported fields
}
BasicNet implements a basic map-backed network whitelist using locks for concurrency. It must be initialised with one of the constructor functions. This particular implementation is unoptimised and will not scale.
func NewBasicNet ¶
func NewBasicNet() *BasicNet
NewBasicNet constructs a new basic network-based whitelist.
func (*BasicNet) Add ¶
Add adds a new network to the whitelist. Caveat: overlapping networks won't be detected.
func (*BasicNet) MarshalJSON ¶
MarshalJSON serialises a network whitelist to a comma-separated list of networks.
func (*BasicNet) UnmarshalJSON ¶
UnmarshalJSON implements the json.Unmarshaler interface for network whitelists, taking a comma-separated string of networks.
type Handler ¶
type Handler struct {
// contains filtered or unexported fields
}
Handler wraps an HTTP handler with IP whitelisting.
type HandlerFunc ¶
type HandlerFunc struct {
// contains filtered or unexported fields
}
A HandlerFunc contains a pair of http.HandleFunc-handler functions that will be called depending on whether a request is allowed or denied.
func NewHandlerFunc ¶
func NewHandlerFunc(allow, deny func(http.ResponseWriter, *http.Request), acl ACL) (*HandlerFunc, error)
NewHandlerFunc returns a new basic whitelisting handler.
func (*HandlerFunc) ServeHTTP ¶
func (h *HandlerFunc) ServeHTTP(w http.ResponseWriter, req *http.Request)
ServeHTTP checks the incoming request to see whether it is permitted, and calls the appropriate handle function.
type HostACL ¶
type HostACL interface {
ACL
// Add takes an IP address and adds it to the whitelist so
// that it is now permitted.
Add(net.IP)
// Remove takes an IP address and drops it from the whitelist
// so that it is no longer permitted.
Remove(net.IP)
}
A HostACL stores a list of permitted hosts.
type HostStub ¶
type HostStub struct{}
HostStub allows host whitelisting to be added into a system's flow without doing anything yet. All operations result in warning log messages being printed to stderr. There is no mechanism for squelching these messages short of modifying the log package's default logger.
type NetACL ¶
type NetACL interface {
ACL
// Add takes an IP network and adds it to the whitelist so
// that it is now permitted.
Add(*net.IPNet)
// Remove takes an IP network and drops it from the whitelist
// so that it is no longer permitted.
Remove(*net.IPNet)
}
A NetACL stores a list of permitted IP networks.
type NetStub ¶
type NetStub struct{}
NetStub allows network whitelisting to be added into a system's flow without doing anything yet. All operations result in warning log messages being printed to stderr. There is no mechanism for squelching these messages short of modifying the log package's default logger.
Notes ¶
Bugs ¶
overlapping networks aren't detected.
Source Files
Directories