YFi Hotspot Manager Wiki

Brought to you by: dvdwalt

yfi_explain_JSON

Labels:

Authors: Anonymous

JSON interface of coova chilli (Revised)

Introduction

This is a revised page on the JSON interface of CoovaChilli.
It is not intended to replace the original which I've created, but should be seen as a natural progression as things got more clear to me over time.

Advantages of the JSON interface

Using the JSON interface and some Java Script you can embed a login page for Coova Chilli in ANY web page on ANY web server.
With the JSON interface you can make use of AJAX techniques to report on usage of a session. This is a nice way to give the user of Coova Chilli feedback on their usage.

Explaining JSONP

We start off with some background on JSONP. With an understanding of this background, the JSON interface of Coova Chilli should be a snap to understand.
This section tries to explain JSONP in as simple as possible terms.
It assumes that the reader has at least limited HTML, Java Script and PHP knowlege.
It will also be of advantage if the reader has access to a web server where they can try the sample code out.

Sample HTML page

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
  "http://www.w3.org/TR/html4/loose.dtd">
<html>
  <head>
   <title>YFi Hotspot Manager</title>
    <script type="text/javascript">

        function clicked(){
            alert("Button Clicked");
             var node = document.createElement("script");
            node.type = "text/javascript";
            node.src = "json_service.php?callback=completed";
            document.getElementsByTagName("head")[0].appendChild(node);
        }

        function completed(arg){
            alert("The argument is: "+arg.one);
        }

    </script>
  </head>
  <body>
    <button type="button" onclick="clicked();">Click Me!</button>

  </body>
</html>

The HTML page does the following:

Displays a button which you can click.

When you click the button, the following happens:

An alert pops up informing you about the action. Click 'OK' to continue.
It will then proceed to create a script element, configure the 'src' attribute of the script element.
After that it will append the script element to thew HTML page's header.
This will cause the HTML page to source the script element over the network.
After the script element finished loading over the network it will call the 'completed' function.
This in turn will call a second alert to pop up with some content of the script element.

JSONP service
The page which gets sourced by the sample HTML page's script element looks as follows:

<?
    header('Content-type: application/javascript');     //Output as JavaScript
    $callback   = $_GET["callback"];                    //What should we wrap the JSON with
    $arr        = array ('one'=>"One Attribute");       //PHP Object
    $json_obj   = json_encode($arr);                    //JSON encode the PHP object
    print $callback."(".$json_obj.");";                 //Wrap the JSON with the callback
?>

It gets called as follows:
"json_service.php?callback=completed"
This is a very simple JSONP service.
The P stands for padded. Pages like these are usually passed a query string. (callback in our example)

They will then wrap the JSON - which is an anonymous Java Script object inside the value of one of the query string's elements. (completed in our example)
It will then look something like the following:
callback_name;
EG completed({"one":"One Attribute"});

This will then effectively cause the Java Script engine of the browser to call the function which the JSONP service was instructed to wrap the JSON in as soon as the script element finished loading itself.
That is the reason 'completed' was called.

Coova Chilli's JSONP service

Coova Chilli offers its own JSONP service much like the above explanation.
Please refer to the following page to read more on Coova Chilli's JSONP Service (which they refer to as an interface)
One bit which is not documented though, is when you log in using pap passwords.
A pap password request will look as follows:
http://192.168.182.1:3990/json/logon?username=XXXX&password=0123456789abcdef
The value of password should be obtained from a UAM JSONP service.
The UAM JSONP service takes a challenge, the cleartext password supplied by the user, and a shared secret between chilli and the UAM JSONP service and do some special encryption on it in order to get in into a format that the Chilli program can understand.

Having an understanding how this fits together will help us to create our own login page which utilise the Coova Chilli's JSONP service.

This section will help you to install and configure the YFi Hotspot Manager's login page.

Introduction

The login facilities provided by YFi Hotspot Manager provides two pages.

A simple as possible HTML login page which sould be the first page to be displayed. This will help to accomodate handheld devices, who's browsers Java Script engines may not be up to spec, or simply missing.
A JSON page which involves the Dojo toolkit's libraries for easy Java Script integration and to interact with Coova Chilli's JSONP service.

Install

Download and install the login page bundle on a web server which will be used to define. You need to fetch it using SVN. Instructions on how to obtain it: SVN Download HOWTO

Configure

It is assumed that you are familiar with Coova Chilli's configuration setup - Where the main.conf file's values is determined by the values of variables defined in /etc/chilli.config.
In this sample, we have a server with an IP of 196.1.2.3 and the coova_json directory is in the root of the web server. We need to ensure that the following values are configured.

Location
File
Comment
Example

Coova Chilli (Server or Access Point)
/etc/chilli/main.conf
Created from the value of HS_UAMHOMEPAGE in /etc/chilli/config
uamhomepage http://196.1.2.3/coova_json/splash.php

Coova Chilli (Server or Access Point)
/etc/chilli/main.conf
Created from the value of HS_UAMFORMAT in /etc/chilli/config
uamserver http:/196.1.2.3/coova_json/hs_land.php

Coova Chilli (Server or Access Point)
/etc/chilli/main.conf
Created from the value of HS_UAMSECRET in /etc/chilli/config
uamsecret greatsecret

Coova Chilli (Server or Access Point)
/etc/chiili/config
Specify HS_UAMSERVER - Used by setup scripts like the firewall script
HS_UAMSERVER=196.1.2.3

Ubuntu Server with Apache
/var/www/coova_json/login.php
Ensure $uamsecret is same as Chilli's
$uamsecret = 'greatsecret';

Ubuntu Server with Apache
/var/www/coova_json/uam.php
Ensure $uamsecret is same as Chilli's
$uamsecret = 'greatsecret';

Ubuntu Server with Apache
/var/www/c2/yfi_cake/setup/coova_json/js/dojo/chilli/Json.js
You may want to use https for extra security
var uam_jsonp = 'http://196.1.2.3/coova_json/uam.php';

Test

Make sure everything work as intended.

You should first be directed to a splash page (http://196.1.2.3/coova_json/splash.php)
This will redirect you to a very simple login page using plain HTML which should be usable by most browsers - INCLUDING simple hand-held devices.(http://196.1.2.3/coova_json/hs_land)
Should you wish to use the more powerful JSON login page, you can select the link which will open a new page with a Java Script enabled DOJO/AJAX/WEB-2.2x and all the buzzwords login screen.

Custom setups

Should you wish to host the JSON login page somewhere on a external website -it can be done!
Just add a div with id='CoovaFeedback' and include the 'include.js' file in any web page.
Be sure to also copy all the 'img' and 'js' and their respective sub-directories to that server.
Also make sure the external site is in the 'uamallowed' list (if not defined in HS_UAMFORMAT or HS_UAMHOMEPAGE)

UAMPORT

The CoovaAP's UAMPORT is different from the the UAMPORT of the compiled version. The one is 3990 and the other 3660.
When a 6 turns out to be a 9, confirm the value of $port inside login.php file.

Closing

Hope you find this login-page suite useful.

Wiki: YfiTechCoovaLogin
Wiki: yfi_setup_nas_coova
Wiki: yfi_setup_svn

YFi Hotspot Manager Wiki

yfi_explain_JSON

JSON interface of coova chilli (Revised)

Introduction

Advantages of the JSON interface

Explaining JSONP

Sample HTML page

Coova Chilli's JSONP service

Using YFi Hotspot Manager's login page

Introduction

Install

Configure

Test

Custom setups

UAMPORT

Closing

Related