Menu ▾ ▴

yfi_explain_coova_json

Anonymous

Connecting to the Internet

This page will discuss the process when someone connects through CoovaChilli Captive Portal to the Internet. It also shows how to use the JSON interface available on CoovaChilli to log in. See the following diagram and the explanation that follows.

  • A person tries to go to google.com. This lets the client send a packet for port 80 on google.com's server through the CoovaChilli Captive Portal.
  • If the client machine has not logged in yet, the traffic will be redirected to a splash page (here called splash.php)
  • After a time-out on the splash page it will be redirected to a login page (here called login.php).

Two Important Configuration Items

  • When you configure the CoovaChilli Captive Portal there are two configuration items that specifies URL's which are very important.
  • These are typically specified in the /etc/chilli/config file in order to override those specified in /etc/chilli/defaults.

Configuration Item
Function
Typical Value

HS_UAMHOMEPAGE
Used as a splash page
HS_UAMHOMEPAGE=http://\$HS_UAMLISTEN/coova_json/splash.php

HS_UAMFORMAT
Used as a login page
HS_UAMFORMAT=http://\$HS_UAMLISTEN/mobile/mobile.php

  • CoovaChilli will add a query string to these URL's which should be something like the following: ?res=notyet&uamip=10.1.0.1&uamport=3990&challenge=0af969874aa833e6989006f0b2f41793&called=08-00-27-56-22-0B&mac=08-00-27-3E-84-A7&ip=10.1.0.2&nasid=Residence_Inn&sessionid=4f2eaf5400000001&userurl=http%3a%2f%2fiol.co.za%2f&md=730D01F4C88F503DF4CBC95B3A980223
  • The values in this query string can then be uses by the login page when trying to log a user in.
  • The following table lists some items in the query string, what they mean and a typical value of it.

Query string Item
Description
Typical Value

res
The result of the connection attempt
notyet

uamip
The IP Address of the Captive Portal gateway
10.1.0.1

uamport
The port on which the Captive Portal will serve web content (/www) and run the JSON web service (/json)
3990

challenge
A challenge that should be used together with the user's password to create an encrypted phrase used to log on
0af969874aa833e6989006f0b2f41793

called
The MAC address of the IP Address of the Captive Portal gateway
08-00-27-56-22-0B

mac
The MAC address of the client trying to gain Internet access
08-00-27-3E-84-A7

ip
The IP Address of the client trying to gain Internet access
10.1.0.2

nasid
An identification for the Captive Portal used in the RADIUS request
Residence_Inn

userurl
The URL which the user tried to access before he were redirected to the Captive Portal's URL's pages
http%3a%2f%2fiol.co.za%2f

The Splash Page

  • To specify the URL of the splash page you need to specify a value for HS_UAMHOMEPAGE in the CoovaChilli config file (/etc/chilli/config).
  • The splash page is typically used to force a logo upon a person with some animated gif graphic telling them they are going to be redirected.
  • After some time-out the user will be redirected to a page that will allow them to log in.
  • You do not have to force this splash page upon the user and can simply redirect them to the login page immediately.
  • To do this simply comment the value of HS_UAMHOMEPAGE out in BOTH the /etc/chilli/config and /etc/chilli/defaults files.
  • Failing to remove the HS_UAMHOMEPAGE value from the /etc/chilli/defaults file will cause the captive portal to use the default file located under /etc/chilli/www.

The Login Page

  • The login page typically contains an html form with a username and password fields that can be submitted by the user.
  • The CoovaChilli Captive Portal also feature a JSON interface. Having a JSON interface we can use Ajax calls to get the status of our connection, to log in and to log out.

Using the JSON interface to do a simple connection

  • We can make use of Coova Chilli's JSON interface to do a simple connection.
  • For this we assume the following:

Item
Value

CoovaChilli gateway
10.1.0.1

Client IP
10.1.0.2

UAM Port
3990

JavaScript Callback
coova_complete

Get our current status

  • http://10.1.0.1:3990/json/status/?callback=coova_complete

  • Here's the feedback on my set-up. 

    coova_complete({"version":"1.0","!clientState":0,"challenge":"de96c43d2b5786312fb97a21940390d2","location":{"name":"My HotSpot"},"redir":{"originalURL":"http://10.1.0.1:3990/status/?callback=coova_complete","redirectionURL":"","logoutURL":"http://10.1.0.1:3990/logoff","macAddress":"08-00-27-3E-84-A7"}})

  • Two items in the reply is important clientState and challenge.

  • ClientState can be 0 which means the client is not connected or it can be 1 which means the client is already connected.
  • Challenge should be used together with the user's password to generate a secure phrase used to log a user in.

Use the challenge to create a pass phrase

Take the response and try to connect

  • We can then take the value of response to try and log in by giving password's value the response feedback of the uam.php script:
  • http://10.1.0.1:3990/json/login?callback=coova_complete&username=dvdwalt@ri&password=d25e267196a1337d6a695485f5e18db6

  • If the connection was successful you will get feedback like the following: 

    coova_complete({"version":"1.0","clientState":1,"redir":{"originalURL":"http://10.1.0.1:3990/connect?callback=coova_complete&username=dvdwalt@ri&password=d25e267196a1337d6a695485f5e18db6","redirectionURL":"","logoutURL":"http://10.1.0.1:3990/logoff","macAddress":"08-00-27-3E-84-A7"},"session":{"sessionId":"4f2eeb7b00000001","userName":"dvdwalt@ri","startTime":21748,"sessionTimeout":0,"idleTimeout":900},"accounting":{"sessionTime":0,"idleTime":0,"inputOctets":0,"outputOctets":0,"inputGigawords":0,"outputGigawords":0}})

  • As you can see the connection was made fine looking at the value of clientState.

  • Should the password be wrong you will be notified in the feedback: 

    coova_complete({"version":"1.0","clientState":0,"message":"Password Incorrect","challenge":"dae5ba16691d4889e4051214d027c0ac","redir":{"originalURL":"http://10.1.0.1:3990/connect?callback=coova_complete&username=dvdwalt@ri&password=d25e267196a1337d6a695485f5e18db6","redirectionURL":"","logoutURL":"http://10.1.0.1:3990/logoff","macAddress":"08-00-27-3E-84-A7"}})

  • Confirm than that the challenge is correct by visiting the status page again and also compare the shared secret between the CoovaChilli Captive Portal and the uam.php page then try again.

Disconnecting

  • As you can see the feedback above includes the logoutURL. To disconnect simply point your browser to it.

http://10.1.0.1:3990/json/logoff?callback=coova_complete

  • Here's the feedback: 

    coova_complete({"version":"1.0","clientState":0,"challenge":"3695b44168811723193c5f37099e7d2d","session":{"sessionId":"4f2eec6400000001","userName":"dvdwalt@ri","startTime":21748,"sessionTimeout":0,"idleTimeout":0},"accounting":{"sessionTime":519,"idleTime":515,"inputOctets":104,"outputOctets":132,"inputGigawords":0,"outputGigawords":0}})

Conclusion

  • The JSON interface makes it very easy to host a login page on a remote server. Now any page can become a login page.
  • There are three action under the JSON service: status, login and logoff
  • Modern JavaScript libraries like JQuery, Dojo or ExtJS allows for easy Ajax login pages using the JSON web services that CoovaChilli has for our disposal.

Related

Wiki: YfiTechCoovaLogin