# OpenNDS Links: [[Networking]] - Github memory page: https://githubmemory.com/repo/openNDS/openNDS ## Documentation https://opennds.readthedocs.io/en/stable/overview.html ## Build from Source - See [[OpenNDS Dev Setup]] - See [[OpenNDS Dockerfile Build from OpenWrt SDK]] ## Installation on [[OpenWrt]] ### For Developers See [[Lightning Router Config#Install OpenNDS fork]] ### For Users (WIP process) - Probably write them a [[Dockerfile]] that installs it automatically - Our [[OpenNDS]] releases will be packaged as part of [[-Projects/-Lightning Router/Lightning Router]] and will be installed directly on the router ### How it works https://opennds.readthedocs.io/en/stable/howitworks.html# - "FAS, or Forward Authentication Service may use the web server embedded in openNDS, a separate web server installed on the NDS router, a web server residing on the local network or an Internet hosted web server" - The user of the client device will always be expected to complete some actions on the splash page. - Once the user on the client device has successfully completed the splash page actions, that page then links directly back to NDS. - For security, NDS expects to receive valid verification of the client. If the verification is valid, openNDS then “authenticates” the client device, allowing access to the Internet. openNDS uses various methods of encryption to ensure verification cannot be bypassed. ### Mobile-first It is important to remember that CPD is designed primarily for mobile devices to automatically detect the presence of a portal and to trigger the login page, without having to resort to breaking SSL/TLS security by requiring the portal to redirect port 443 for example. For a typical guest wifi, eg a coffee shop, bar, club, hotel etc., a device connects, the Internet is accessed for a while, then the user takes the device out of range. When taken out of range, a typical mobile device begins periodically polling the wireless spectrum for SSIDs that it knows about to try to obtain a connection again, subject to timeouts to preserve battery life. Most Captive Portals have a session duration limit (NDS included). If a previously logged in device returns to within the coverage of the portal, the previously used SSID is recognised and CPD is triggered and tests for an Internet connection in the normal way. Within the session duration limit of the portal, the Internet connection will be established, if the session has expired, the splash page will be displayed again. The vast majority of devices attaching to a typical Captive Portal are mobile devices. CPD works well giving the initial login page. The best solution is to set the session timeout to a value greater than the expected length of time a client device is likely to be present. Experience shows a limit of 24 hours covers most situations eg bars, clubs, coffee shops, motels etc. If for example an hotel has guests regularly staying for a few days, then increase the session timeout as required. ### Multiple WiFi SSIDs Client devices can be connected to one of a number of local WiFi SSIDs, connected directly or indirectly by ethernet, or connected via a wireless mesh network. Each connection type available is considered as a Network Zone. NDS detects which zone each client is connected to. This information can be used to dynamically customise the login for each zone For example a coffee shop might have two SSIDs configured: Staff (Secure SSID ie with access code) Customers (open SSID with login form) In this example SSID “Staff” is configured on interface wlan0, and considered as Zone “Private”. However, SSID “Customers” is configured on virtual interface wlan0-1, and considered as Zone “Public”. NDS detects which zone is being used by a client and a relevant login page can be served. ## Packet filtering openNDS considers four kinds of packets coming into the router over the managed interface. Each packet is one of these kinds: 1. Blocked, if the MAC mechanism is block, and the source MAC address of the packet matches one listed in the BlockedMACList; or if the MAC mechanism is allow, and source MAC address of the packet does not match one listed in the AllowedMACList or the TrustedMACList. These packets are dropped. 2. Trusted, if the source MAC address of the packet matches one listed in the TrustedMACList. By default, these packets are accepted and routed to all destination addresses and ports. If desired, this behavior can be customized by FirewallRuleSet trusted-users and FirewallRuleSet trusted-users-to-router lists in the opennds.conf configuration file, or by the EmptyRuleSetPolicy trusted-users EmptyRuleSetPolicy trusted-users-to-router directives. 3. Authenticated, if the packet’s IP and MAC source addresses have gone through the openNDS authentication process and has not yet expired. These packets are accepted and routed to a limited set of addresses and ports (see FirewallRuleSet authenticated-users and FirewallRuleSet users-to-router in the opennds.conf configuration file). 4. Preauthenticated. Any other packet. These packets are accepted and routed to a limited set of addresses and ports (see FirewallRuleSet preauthenticated-users and FirewallRuleSet users-to-router in the opennds.conf configuration file). Any other packet is dropped, except that a packet for destination port 80 at any address is redirected to port 2050 on the router, where openNDS’s built in libhttpd-based web server is listening. This begins the ‘authentication’ process. The server will serve a splash page back to the source IP address of the packet. The user clicking the appropriate link on the splash page will complete the process, causing future packets from this IP/MAC address to be marked as Authenticated until the inactive or forced timeout is reached, and its packets revert to being Preauthenticated. ## Wrinkle: Rules for Customised Splash Pages It should be noted when designing a custom splash page that for security reasons many client device CPD implementations: - Immediately close the browser when the client has authenticated. - See [[-Projects/-Lightning Router/Lightning Router#Prevent Captive Portal auto-close after authentication Android]] for a workaround on Android - Prohibit the use of href links. - An href to stylesheet is included in the default `splash.html` (in ``/etc/opennds/htdocs`) - Prohibit downloading of external files (including .css and .js, even if they are allowed in NDS firewall settings). - Prohibit the execution of javascript. - Googling around for "captive portal detection implementations prohibit javascript", I can't seem to find much evidence that this is the case. It is possible that this information is outdated. - We should, at least, make sure that any assets that the user needs (css, js, images etc) are available locally from the router itself or the daemon / api service accessible on the local network. My Mullvad killswitch for example won't let me go to google.com before I've been authenticated, but I can ping devices on the local network, which would include the router and daemon / api ## Config ### Set Rate Quotas https://opennds.readthedocs.io/en/stable/config.html#set-rate-quotas "If the client average data rate exceeds the value set here, the client will be rate limited." - Doesn't appear to apply to individual clients - Shouldn't be too hard to add a boolean to each client indicating whether the rate limit applies `option uploadrate '200'` `option downloadrate '800'` ### Set Volume Quotas https://opennds.readthedocs.io/en/stable/config.html#set-volume-quotas If the client data quota exceeds the value set here, the client will be deauthenticated. The client by default may re-authenticate. `option uploadquota '1000'` `option downloadquota '10000'` ### Set PreAuth https://opennds.readthedocs.io/en/stable/config.html#set-preauth `option preauth '/path/to/myscript/myscript.sh'` ### Access Control For Preauthenticated Users: https://opennds.readthedocs.io/en/stable/config.html#access-control-for-preauthenticated-users **IMPORTANT** - Preauthenticated users do not require access to anything on the Internet for the Captive Portal to work. - In particular, to help prevent DNS tunnelling, DNS Hijacking and generally improve security, DO NOT allow access to external DNS.