Documentation ¶
Overview ¶
Package captive provides a TCP/IP proxy for HTTP/HTTPs traffic controlled by a user-defined captive portal (client-IP based).
In order to use the portal, TCP traffic for ports 80 and 443 must be forwarded to the portal ports (usually this is done using "iptables").
The proxy acts as a man-in-the-middle only letting through HTTP(s) traffic from IPs which have been allowed. Along with the proxy, captive.Portal runs HTTP servers to redirect and serve the portal website, which is user-defined. The portal server handles a login endpoint which allows clients to be whitelisted based on a user-provided function.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Portal ¶
type Portal struct { // The TCP port to capture or allow HTTP requests through. 8080 by // default. HTTPPort int // The TCP port to allow HTTPs requests through. 8081 by default. HTTPSPort int // If you want to serve the portal with HTTPS, set CertFile and KeyFile // to a valid path. The certificate must be valid for the PortalDomain. CertFile string KeyFile string // The path on disk of the Portal website shown to unlogged users and // seemingly running on PortalDomain. This should be a folder with at // least an index.html in it and is served using http.FileServer. WebPath string // The path to handle users logins and potentially allow HTTP and HTTPs // traffic. POST requests will trigger the LoginHandler and return // either 202 (Accepted) or 401 (Unauthorized). // GET requests will return 204 for authorized clients, or 403 // for the rest. This should not be "/". LoginPath string // The captive's portal domain. Users get redirected here and served // the contents from the WebRoot directory. This domain must exist and // be resolvable. Otherwise browsers will not make requests to it. PortalDomain string // Additonal subdomains to handle (i.e. "www", "login"). Defaults // to ["www"]. PortalSubdomains []string // Are allowed clients shown the portal at all or are they let // through to the actual real PortalDomain site. AllowedBypassPortal bool // A Handler for LoginPath. Returns true if the client's traffic // should be let through or false otherwise. Not setting this will // authenticate all clients that request it. LoginHandler func(loginReq *http.Request) bool // An optional path to run the user-provided CustomHandler. This // allows the Portal to implement any other server-side functionality. CustomHandlerPath string // An optional custom http.HandleFunc to be called for // requests to CustomHandlerPath CustomHandler func(w http.ResponseWriter, r *http.Request) // contains filtered or unexported fields }
Portal creates a tcp/ip proxy for HTTP and HTTPs traffic that can be launched with Run(). Clients whose IPs have not been allowed are redirected to the PortalDomain. Clients visiting the PortalDomain will be served the website contents in WebPath.
HTTP POST requests to LoginPath are used to allow clients by executing the LoginHandler function. If successful, traffic from authorized clients is let through to its original destination. GET requests to login path can be used to determine if a user is whitelisted or not.
The captive portal operates on the TCP/IP layer, thus the client IP is used for authentication (and not MAC address -yet).