ZeroShell    Forum
   Feed RSS Feed
EnglishEnglish     ItalianoItaliano     French     Spanish                Zeroshell on LinkedIn LinkedIn       Facebook      Twitter ZeroTruth an interface for Captive Portal

      What is it?
      Mailing List
      On-line Updates
      Kerberos Tutorial  
      Terms of use
      Contact me

  In greater details:
      Hotspot Router
      RADIUS Accounting
      Shibboleth SP
      Net Balancer
      UMTS Router
      Soekris Net5501
      Proxy with Antivirus
      WiFi Access Point
      OpenVPN Client
      OpenVPN Server
      Kerberos 5
      NIS and LDAP
      X.509 Certificates

Valid HTML 4.01 Transitional

Hotspot router for authenticated network access

The purpose of this document is to describe the implementation of a gateway for Wi-Fi hotspots using Zeroshell. We will focus especially on how to authenticate users (RADIUS, Kerberos 5 and X.509 digital certificates) and on the RADIUS accounting for traffic, time and cost of the connections. It will take a look at the possibility of obtaining multi-WAN router with balancing and failover of the Internet connections and functionality of Captive Portal.

Hotspot network protected by a Captive Portal Router
Fig.1 Hotspot network protected by a Captive Portal Router

The content of this document is subdivided into the following sections:


In the hotspots, that is in public places where Internet access is given to occasional users, at least some of the following features are required:
  1. Authentication of the users
  2. Logging of the accesses to the network;
  3. Accounting for traffic, time and cost of the user connections.
The authentication, that is the ability to uniquely identify the user and then grant access to the network, it can be done via username and password or through a X.509 digital certificate that could be stored on smart card.
The access log is sometimes required by law, because it allows us to trace the perpetrators of illicit activities. Mind you that logging does not include registration of URLs or worse content that the user had access, but simply record the date and time of start and end of each of the connections to the Internet of the user and the IP address associated with the client (usually a laptop) from where the connection took place.
The accounting, however, in addition to tracking the beginning and end of the connection, record the time and traffic for connection of a user. Often the purpose of accounting is to allow the charging of costs for traffic in Megabytes and time in minutes of connection. In addition, through accounting, you can set limits on traffic and time over which the user is disconnected from the network. In particular, the accounting can allow the management of prepaid connections in which the user must have a Credit to be online.

In order to obtain this functionality you can use one or both of the following methods of access:
  • Authentication and traffic encryption via WPA/WPA2 Enterprise
  • Captive Portal
WPA/WPA2 Enterprise, which requires Wi-Fi Access Points associate a client only if the user has valid credentials verified by a RADIUS server using 802.1x. In addition to authentication, traffic encryption is also guaranteed between client and Access Point.
In the case of access via captive portal instead, the Access Points are programmed in open mode, that is without any authentication and encryption. The client can associate freely and immediately receives an IP address from DHCP server. However, the gateway to the Internet access blocking communication with the outside and redirects any web request (http and https) to an authentication page.

It soon becomes clear that WPA/WPA2 Enterprise is a more robust system in terms of security compared to the captive portal, but on the other hand, it requires the user to configure his client (supplicant) to authenticate via 802.1x. This configuration is not easy for occasional users of a hotspot and for this reason, which in most cases, we prefer to give access using captive portal that requires no configuration on the mobile devices.

Captive Portal Gateway configuration
Captive Portal Gateway configuration

Some Wireless Access Points internally implement a captive portal, but often this is not configurable and adaptable to the needs of a hotspot. It is more flexible and convenient to use low cost WiFi Access Points, without any advanced feature and refer the captive portal function to a router that acts as a gateway to the Internet as shown in figure 1

The enemies of the Captive Portal

The simplicity in the use of a captive portal even by a novice user is mainly due to the fact that access to Level 2 of the network, whether it is wireless and wired network is open (that is no authentication is required). The client just is associated the network immediately obtains an IP from the DHCP server and communicates in a non-encrypted way. The counterpart to this simplicity translates into an inherent weakness in terms of security. We will see in the next two paragraphs as Zeroshell attempts to mitigate this weakness.

Spoofing of the IP and the MAC addresses

The security issue longer felt when talking about Captive Portal is spoofing the IP and MAC addresses of network card. In fact, the firewall of the Captive Portal unlocks clients authenticated by identifying the IP and MAC addresses (the latter only if the captive portal is directly connected at layer 2 of the network to be protected, that is there are no router half). Unfortunately, these 2 parameters can be set easily on any operating system and therefore, there is a risk that someone with a sniffer captures traffic looking for a client already authenticated and set the same IP and MAC addresses. This would disturb the communication of the client legitimately authenticated that noting a low connection quality, abandons the use of the Internet, leaving space to fraud.
The problem is made worse by the fact that most of the captive portal implementations maintain an authenticated client connected until it is visible on the network without the client actively participate in the renewal of authentication. Some implementations check the ARP table to see if the client has recently made traffic or perform an ARP Request for checking the presence of the IP on the network. Others use the table of the leases of the DHCP server, checking whether the client has requested the renewal recently. These solutions are clearly insecure, because the client has a passive role in the reaccreditation of authentication.
Zeroshell's solution is instead to ensure that the client itself is to ask the captive portal gateway the renewal of the authentication, presenting a packet encrypted with AES256, called Authenticator. This is a secret shared only by the client and by captive portal (it travels in the SSL tunnel and therefore can not be captured with a sniffer), so even if someone sets the IP and MAC address of an authenticated user will not have the Authenticator required by the captive portal to renew the authentication. The Authenticator is stored by the client in a popup window called Network Access Popup that handles using Java Script to send it to the captive portal for renewal.

Network Access Popup window
Network Access Popup window

The popup window also performs other functions, such as to allow the user to disconnect and view useful accounting information such as time, traffic and cost of the connection. It should be noted that this window is not blocked by anti-popup which comes with almost every web browser because it is opened by a synchronous request for user authentication. On the other hand, the popup window has caused several problems with the advent of mobile devices such as the iPhone, the iPad and other smartphones and PDAs (including Windows Mobile and Android) that not having a multitasking system actually forgot to renew the authentication causing the closure of the connection. To remedy this problem, since the release 1.0.beta15 of Zeroshell, Mobile devices are recognized by the captive portal that does not impose them the renewal of authentication by sending the Authenticator, but simply verifying their online presence.

Smartphones and other Mobile Devices configuration
Smartphones and other Mobile Devices configuration

Denial of Service (DoS)

Some software in an attempt to communicate with the outside network at any cost, after attempting to communicate on the TCP/UDP ports assigned to them, try the connection on TCP ports 80 and 443 knowing that is not easy that a network administrator would close the outgoing traffic on these ports preventing the http/https navigation and hence access the web. The best known example of this category of programs is the Skype VoIP client, but many other P2P systems and worms have the same behavior. You can imagine immediately that when a user is associated with its clients to the network, but not yet authenticated by the Captive Portal, such requests on the TCP ports 80 and 443 will be redirected to the authentication portal which would try unsuccessfully to serve them given that the traffic is not HTTP. It is obvious that more the clients are not authenticated yet and run these programs, more it increases the probability of occurrence of a DoS (Denial of Service) in which the portal of authentication is committed to serving fake requests, failing to operate or handle very slowly rightful requests from web browsers.
Zeroshell restricts the occurrence of such situations by implementing a system of DoS Protection using the Linux Netfilter to limit the maximum number of redirects per minute. The protection level can be set on three levels (Low, Medium e High).

Captive Portal Denial of Service Protection
Captive Portal Denial of Service Protection

In addition, the mechanisms of Auto-Update of the Operating Systems and of the Antivirus Signatures often use the http protocol to communicate with the updating repository and therefore may exacerbate the situation, making requests that are added to the workload of the Captive Portal. Again Zeroshell attempts to contain the problem by intercepting requests to the most common repository avoiding unnecessary redirect to the authentication page of the Captive Portal.

Router or Bridge?

In Figure 1 the captive portal works as a Level 3 router connected directly to a modem which connects to the Internet. It acts as the default gateway for clients that connect to the network. In this configuration, said in Routed Mode, it is convenient the router performs the function of DHCP and DNS servers.

The Zeroshell's Captive Portal can also work in Bridge Mode, where the network to be protected by the Captive Portal shares the same IP subnet as the rest of the LAN. Therefore, a client gets the same IP address if you connect from one side than the other and has the same default gateway that is a router ahead of the Captive Portal. In this case, DHCP and DNS to be used for the hotspot may be the same as those used for the rest of the LAN.

In previous versions of Zeroshell you had to explicitly declare the operating mode (Routed or Bridge) of the captive portal. Since the release 1.0.beta15, however, there are 2 news about:
  1. It is handled the MULTI interface where you can declare multiple network interfaces on which to activate the Captive Portal. As shown in Figure Captive Portal can also be enabled on 802.1q VLAN (Virtual LAN Tagged);
  2. Zeroshell selects the bridge or router mode automatically checking whether or not an interface is part of a bridge.
Putting together the two innovations, one deduces that the Captive Portal of Zeroshell can work simultaneously on the same hardware box as a router for some LAN segments and as a bridge for others.

Captive Portal applied on multiple network interfaces
Captive Portal applied on multiple network interfaces

User Authentication

The Captive Portal of Zeroshell can use different authentication sources simultaneously. By default, it authenticates users using its Kerberos 5 KDC that contains principals for internal users stored in the LDAP Directory and managed through the web interface. However, you can use external authentication sources such as Kerberos 5 REALMs, RADIUS servers and Identity Providers SAML 2. In addition, there is also the login using X.509 digital certificates that would allow access the network via Smart Card or USB Token.
In the case of RADIUS or Kerberos 5 authentication the users can come from different domains. In this case, the user must select the authentication domain using the selection box on the access page or by qualifying its username by using @domain suffix (for example

Authorized Authentication Domains for the hotspot
Authorized Authentication Domains for the hotspot


RADIUS authentication is one of the most widely used protocols for the recognition of users on network devices such as Wireless Access Points or layer 2 Switches that allow access to level 2 only after authentication has been successful. The Captive Portal of Zeroshell allows RADIUS authentication requests to external servers via proxy. In other words, the captive portal requires authentication to its internal FreeRADIUS server, that if it discovers that it is not authoritative for the domain to which the user belongs, it forwards the authentication request to the external authoritative RADIUS server. Clearly, the external RADIUS server must be configured in the list of proxy servers by specifying the Shared Secret. On the other hand, even on the external RADIUS server, an entry must be added between the RADIUS clients to enable the IP address of the Captive Portal using the same shared secret. In the list of RADIUS proxy, you can add the DEFAULT RADIUS server that is used when none of the other servers is authoritative for authenticating the user. The default proxy radius is often used even when the captive portal has to authenticate against a RADIUS server hierarchy.

Distributed Hotspots by using a centralized RADIUS server
Distributed Hotspots by using a centralized RADIUS server

The captive portal can make authentication requests via PAP or 802.1x (EAP-TTLS with PAP and PEAP with MSCHAPv2). In the latter case, the captive portal appears to the RADIUS server as a supplicant that attempts to access WiFi network via WPA/WPA2 Enterprise. The use of 802.1x is recommended over the simple PAP if you need a higher level of security, guaranteed by TLS protocol which EAP-TTLS, PEAP (EAP Protect) use.

Kerberos 5 (Active directory)

The Kerberos 5 authentication allows captive portal to interface to a Windows Active Directory domain. In fact, each Windows Server that is a domain controller has a Kerberos 5 KDC that authenticates users in the Active Directory domain to which it belongs. Therefore, just add to the captive portal authorized domains the name of the Active Directory domain to allow Windows users to access the network. Note that if the automatic discovery of the REALM and KDC via DNS SRV records is not active you need to manually specify the IP addresses (or FQDN hostnames) of the authoritative KDC REALM.

Kerberos 5 realms configuration
Kerberos 5 realms configuration

In some situations it could be needed to allow access via captive portal only to user that belongs to a group. This is not possible using Kerberos 5, since it only handles the Active Directory authentication while authorization is delegated to LDAP. However, you can turn on the domain controllers, the IAS (the RADIUS service of Active Directory) and configure the captive portal to authenticate against RADIUS. In this case, you can configure IAS to authorize only users who belong to a selected group.

X.509 Digital Certificates (Smart Cards)

Authentication via X.509 digital certificates allow to access the network without typing your username and password. In other words, each user who needs access to the network must have a personal certificate with its private key loaded into the web browser. Pressing the [X.509] button in the authentication portal, if the certificate is signed by a Certificate Authority enabled within the captive portal configuration, the user has access to the network. The use of digital certificates is often related to that of the Smart Cards or of the USB tokens. These devices may keep the digital certificate in an extremely secure way because the private key can not be extracted with a read operation from the outside. Smart Cards are therefore equipped with their own processor chip that carries out the encryption and decryption requests via the API. To unlock the private key used by the browser the Smart Card requires entering a PIN, which helps to increase security if the card is lost.

Shibboleth (IdP SAML 2.0)

Using Shibboleth Service Provider, the Captive Portal of Zeroshell allows user authentication against an Identity Provider SAML 2. This is often used in the federations in which each member of a federation implements an IdP to recognize users and several web services (Service Provider). These services can include access to a Wi-Fi network, in which the user is redirected to the WAYF/DS from which he/she selects the Identity Provider authoritative to authenticate it. It could be argued that attaching the captive portal to a hierarchy of RADIUS servers (such as EDUROAM with regard the Universities and the Research Institutions) would be however a federated access to the network. However, while in the case of 802.1x the so-called end-to-end authentication takes place also crossing the hierarchy of RADIUS servers, with the captive portal that is not guaranteed. Therefore, it is preferable to use SAML, where instead, credentials travel, starting from the user's browser to its authoritative IdP, always within the same SSL-encrypted tunnel, thereby guaranteeing the end-to-end authentication. More details on the Shibboleth Captive Portal are available on the document Configure the Captive Portal to authenticate users against an IdP SAML 2.0 using Shibboleth.

Accounting for time, traffic and cost of the connections

The accounting allows us to know, for each user, the time, the traffic and the cost of the connections. The Captive Portal of Zeroshell uses the RADIUS protocol to transmit such information, so you can use an external server that supports the RADIUS accounting or just accounting module inside Zeroshell based on FreeRADIUS. As the authentication, also the accounting can be centralized on a single RADIUS server that collects information from multiple hotspots. In addition, keep in mind, that the accounting system of Zeroshell can, because it meets the standard RADIUS, collect information also directly from the Wi-Fi Access Point that use WPA/WAP2 Enterprise with 802.1x.

RADIUS Accountig information
RADIUS Accountig information

User accounting details
User accounting details

Network access limits

Using RADIUS accounting it is possible also set connection limits for users. To do this, simply assign the users to a class of accounting to which you give the following parameters:
  • Kind of payment (prepaid and postpaid)
  • Cost per megabyte of traffic
  • Cost per hour of the connection
  • Maximum limit of traffic (incoming and outgoing) in Megabytes
  • Time limit of connection

User limits configuration in the accounting
User limits configuration in the accounting

Logging of user accesses and TCP/UDP connections

Although already the accounting keeps track of user connections to the network it is possible to have more details on user authentication, looking at log messages referring to the Captive Portal.

Log message of the Captive Portal
Log messages of the Captive Portal

Moreover, especially if the clients of the captive portal using private IP addresses, it can be useful to keep track of TCP and UDP connections that are established with external servers, since the captive portal must perform NAT (Network Address Translation), all connections appear generated by the router's public IP. The logging of the Connection Tracking must be explicitly enabled and it is recommended to assess, before you enable it, that its use is permitted by privacy laws, taking into account the fact, that it can not be used to know the contents of users' communications, but only to determine what servers have been contacted.

Connection Tracking of the TCP/UDP connections
Connection Tracking of the TCP/UDP connections

Load Balancing and Fault Tolerance of the Internet Connections

In order to ensure adequate and stable bandwidth for Internet you can enable load balancing and fault tolerance for WAN links. Zeroshell can work in two modes called Failover and Load Balancing and Failover. In the first case all traffic is routed by the link most efficient, while other connections are spares and only take place in case of failure of the active one. In Load Balancing and Failover mode, instead, all connections are simultaneously active and the traffic is routed over them in round-robin. Even in the latter case is guaranteed fault tolerance, since, if a link is inaccessible is automatically excluded from the balancing until it returns accessible.
In addition, you can balance the traffic manually. For example, you may decide that VoIP traffic is routed by a link, while that generated by the transfer of files from one another. This will avoid saturating the link that would produce noise in the VoIP communications. For more details, read the document Multiple Internet Connections by Balancing Traffic and Managing Failover.

    Copyright (C) 2005-2013 by Fulvio Ricciardi