The idea behind Coova is simple: to provide you with the open (and free) tools and services you need to manage and access your WiFi network, just the way you want to. Our philosophy is that you shouldn’t be required to use any specific hardware (like FON or Meraki) or software (like Whisher). From the ground up, Coova is about being open and standards based - compatible with the widest possible range of hardware, protocols, and services. It’s about bringing “Carrier” grade features and services to the open-source/services world. It’s also about making dumb routers a bit smarter - recycling is good, right?

With Coova, you can pick and choose the software and services you need - depending on the kind of network you are building and how you want to access it. Here are some typical uses of Coova technologies:

• Use CoovaAP for easy configuration of CoovaChilli (or WiFiDog):
  • with or without using CoovaAAA services,
  • using RADIUS or locally defined users,
  • using the customizable “Internal” captive portal, or
  • configured to use your own portal or RADIUS service.
• Use CoovaChilli either in CoovaAP or in your own firmware or server to:
  • enforce a captive portal and authentication using CoovaAAA or any other portal/RADIUS service,
  • works with a variety of commercial services (ask your provider),
  • integrate with 802.1X authentication to provide accounting and access limitations.
• Use CoovaAAA to manage the access to your network:
  • with a CoovaChilli/AP captive portal,
  • using a patched WiFiDog captive portal,
  • using your own captive portal (no advanced programming needed),
  • using our Facebook or standard captive portal applications,
  • using a commercial access controller (like Colubris), or
  • using any router supporting WPA Enterprise/802.1X (like the AirPort Extreme).
• Use and share your CoovaAAA controlled network:
  • using one account to login to both your captive portal and your secure WPA Enterprise networks (using any device supporting 802.1X, like your laptop or Nokia phone),
  • using your account at any CoovaAAA location that is being shared with you,
  • selectively share your network with only those you choose - individuals or entire realms, or
  • share your network based on OpenID logins or Facebook fans/friends.
• Use CoovaFX and CoovaSX in Firefox or your phone, respectively, to login past a captive portal using the WISPr standard and a pre-configured account - WISPr is supported by CoovaAAA and most commercial access controllers and service providers.

• Use JRadius to program your own RADIUS provisioning logic for your network.

If you are building a WiFi network and haven’t found anything on this site that can help you, you probably haven’t looked hard enough. Though, it has been said, and we do acknowledge, that more documentation is needed. For this, we call out to the development and user community to help out in the Wiki (click on the “* wiki” to create an account and login), forums, and mailing lists. Note: In the Wiki, we do lock pages to prevent SPAM - either create a new page or ask for more permissions on one of the mailing lists.

We are also hoping to hear more about how and where you are using Coova! In fact, a friend of mine was recently vacationing in the Dominican Republic and was pleasantly surprised to find a Coova signal at the Hotel. They were using CoovaAP for their WiFi. Stories like this are terrific — lets get them in the forum!

Introducing CoovaSX

I recently acquired a Nokia N95 8GB smartphone and started using the WiFi features before making my first voice call. I immediately was annoyed with my own captive portal and having to key in my username and password each time I wanted online - not to mention having to navigate a webpage not made for small displays. The picture on the right shows the embedded browser on my Facebook landing page.

The embedded browser would remember my username (until the cache gets cleared), but never my password. There is now an easier way to login your Java-capable smartphone to your captive portal hotspot - using CoovaSX 1.0! Similar to the firefox extension CoovaFX, but for your phone, CoovaSX will log you into your hotspot without going through the captive portal. Configure your username and password once, then use CoovaSX to login before using the Internet - all without using your browser.

To use the application, your phone must support Java MIDlets (MIDP-2.0). CoovaSX works at hotspots with a captive portal supporting the WISPr XML method of authentication. Visit us in the forum with your comments, questions, or suggestions.

CoovaChilli Update

Now in subversion are some updates to CoovaChilli - which include:

• New options dhcpgateway and dhcpgatewayport to specify a DHCP gateway (relay) host IP address and port,
• New option dhcpradius for mapping some DHCP options into RADIUS attributes and visa versa during MAC authentication, as described here,
• New internal state called splash in which clients are given Internet access, but enforcing the port 80 http redirect,
• New option macauthdeny which will result in the black-listing of devices given an Access-Reject during MAC address authentication, and
• Code cleanups, reorganization, and bug fixes.

Binaries will become available through the forum, where you can also report problems or offer suggestions. For more information on changes in Chilli, see the ChangeLog.

Funding

Just like FON, with their recent $9.5 million round of funding (commentary here), Coova too needed to raise some money. Though, not on such a scale. We had to plop down an extra $550 for a 2 year code signing certificate from Thawte …

CoovaChilli & CoovaAP support

It is great to see CoovaChilli and CoovaAP being used and supported by more companies and projects! FON has been using CoovaChilli, Open-Mesh.com plans to, supported by Worldspot, and Coova officially works with Radiator. In fact, CoovaChilli will work with any RADIUS server and it is used by countless wireless ISPs, of all sizes, around the world. CoovaAP, an OpenWrt-based firmware for commodity WiFi routers, provides an easy to configure platform for CoovaChilli access controlled networks and WiFiDog captive portal community networks alike.

WiFi-CPA, a commercial hotspot service company, also uses CoovaChilli and CoovaAP, though it might not be as obvious. They re-branded and modified CoovaAP (which is not ideal, but ok when done right), took and doctored a diagram from this website (removed; thanks!), yet don’t even mention or link to Coova.org (also remedied). They say imitation is a form of flattery; what about copyright infringement? There is also some confusion around the chillispot.info website. As far as I can tell, this is a copy of the original ChilliSpot.org website (with commercial links added) and is not continuing with any development. It does, however, provide a forum for ChilliSpot die-hards, which is helpful for some.

Here at Coova, development is continuing toward a 2.0 release (for both CoovaChilli and CoovaAP), with the emphasis being on stability, performance, and remote manageability — in addition to new features, including those described here in the blog and perhaps here in the forum; not to mention ideas for mesh integration. As with many open-source projects, community involvement, commercial support, and feature ’sponsorships’ are important and welcomed. Thanks to all those who submitted bug reports, suggestions, or patches in the forum!

JRadius & FreeRADIUS user interface

I have been using FreeRADIUS for some time - usually as the front-end to a JRadius server. FreeRADIUS is both powerful and flexible, but I believe many would agree that what it needs most is a graphical user interface. It could also benefit from pre-cooked configurations for typical deployments. Indeed, the same could be said for JRadius and the configuring of it’s handers. Perhaps CoovaEWT can be of assistance. CoovaEWT is a web-based user interface framework that is in development. The “compiled” Ajax (javascript/html) application is free to use and highly extensible using XML and XSLT. The user interface definition itself, the configuration it edits, and the scripts to generate the final application configuration files (e.g. radiusd.conf) are all customizable server-side files. Below are some screen-shots of what’s in development in JRadius.

Above is a typical screen from the FreeRADIUS administration interface - to configure the interfaces, in this case.

In addition to configuring the FreeRADIUS server itself, the user interface is ideal to manage the database tables that come with the SQL module.

Backed by the JRadius dictionary, which is generated from FreeRADIUS dictionary files, the interface is able to help you complete attribute names, so you don’t make any spelling mistakes. More news to come… stay tuned to the JRadius wiki, forum, and mailing list.

CoovaFX on the road

For fun on a recent trip to London, I took a couple screen-shots of the WISPr-enabled networks CoovaFX picked up in various places. I used CoovaFX to log into my hotel network with a voucher username and password I had to buy (boy, WiFi is expensive in London).

There is a standard known to some as WISPr XML - which provides a convenient way for non-browser based authentication on captive portal networks. The technique is used by a variety of smart-client and access controller vendors. Chilli, as an access controller, has long had support for WISPr; initially funded by WeRoam in the original ChilliSpot. Support for WISPr continues in CoovaChilli, and here is how to use it. To test and use this method of authentication to login, albeit, from the browser, install the new Coova Firefox Extension. Tested against CoovaAP and Colubris, it should work with any WISPr implementation.

What does it do? First, the extension checks to see if you are online. It does this by trying to access a page on the Internet - a page not in the walled garden. At Hotspots supporting WISPr, the access controller sends back some XML along with the initial browser redirect to the captive portal. Smart-client applications use this information, which includes the hotspot location name, to login to the network. This extension does the same thing, plus it:

The Dynamic Host Configuration Protocol (DHCP) is a standard way for client devices to acquire an IP address and other configurations (DNS, Gateway, etc) on a network. This is particularly true in public access networks; as such, DHCP is integral to chilli, and always has been. Of course, it could certainly be more flexible. As it is now, you can’t really do much in the way of customizing your DHCP configurations. I have some ideas for CoovaChilli, and some DHCP discovery to share.

DHCP and MAC Authentication

MAC authentication is a common feature to access controllers that perform DHCP. It allows for authentication to take place automatically without the need of a captive portal or a web browser. CoovaChilli (and ChilliSpot) has the option to authenticate MAC addresses. Using this feature, initial DHCP requests made by the client trigger a RADIUS Access-Request. Subsequent DHCP requests from the client are granted with an authentication state based on the RADIUS response being Access-Accept or Access-Reject. That will change with the macauthdeny option, to have Access-Reject mean complete black-listing, but more could be done.

Here are the DHCP options found in a request from a Windows XP laptop (the Parameter Request List being the same in DHCP Discover messages):

Option 53: DHCP Message Type = DHCP Request
Option 61: Client identifier
    Hardware type: Ethernet
    Client MAC address: 00:18:xx:xx:xx:xx (00:18:xx:xx:xx:xx)
Option 12: Host Name = "laptop"
Option 81: FQDN
    Flags: 0x00
    A-RR result: 0
    PTR-RR result: 0
    Client name: laptop.coova.org
Option 60: Vendor class identifier = "MSFT 5.0"
Option 55: Parameter Request List
    1 = Subnet Mask
    15 = Domain Name
    3 = Router
    6 = Domain Name Server
    44 = NetBIOS over TCP/IP Name Server
    46 = NetBIOS over TCP/IP Node Type
    47 = NetBIOS over TCP/IP Scope
    31 = Perform Router Discover
    33 = Static Route
    249 = Classless static routes
    43 = Vendor-Specific Information
End Option

The following Vendor Specific Attributes (VSA) are proposed additions to CoovaChilli in order to forward this information to the RADIUS server during MAC authentication:

DHCP Option                          RADIUS Attribute
--------------------------------     --------------------------------    
Option 12: Host Name                 ChilliSpot-DHCP-Hostname
Option 55: Parameter Request List    ChilliSpot-DHCP-Parameter-Request-List
Option 60: Vendor class identifier   ChilliSpot-DHCP-Vendor-Class-Id
Option 61: Client identifier         ChilliSpot-DHCP-Client-Id
Option 81: FQDN                      ChilliSpot-DHCP-Client-FQDN

Additionally, the VSA named ChilliSpot-DHCP-Options will be optional in either an Access-Accept or Access-Reject, carrying arbitrary options to append to the DHCP response. All attributes are binary octet strings and carry the DHCP options in raw form.

Attributes in the Access-Request contain the corresponding DHCP option value, whereas the ChilliSpot-DHCP-Options contains a list of options, packed as they are in a DHCP message. Combined with the existing support for the Framed-IP-Address RADIUS attribute for IP assignment, this method provides for a high level of DHCP configuration centralized in your RADIUS server.

DHCP Relay Gateway

As the MAC authentication feature has shown, there is no reason why chilli can’t delegate IP assignment. Then why not have chilli act as a DHCP forwarding agent? This would make it possible to centrally manage your DHCP configurations, using a more configurable server. CoovaChilli will be able to forward DHCP requests to a remote DHCP gateway, noting the IP assignment in the response.

This would open up many possibilities… including, perhaps, captive portal settings provisioned through a DHCP server!

Note: You can already use CoovaChilli with access points, like the Cisco Aironet, configured to forward DHCP to chilli.

WPAD and Proxy Autoconfigure

Windows has a feature (in Internet Options, Connections tab, LAN settings button, Automatically detect settings checkbox) whereby browser proxy configurations can be picked up automatically from a network. The Web Proxy Auto Discovery (WPAD) protocol provides browsers (primarily Windows Internet Explorer, and maybe others) with a proxy configuration file. This Proxy Auto-Config (PAC) file can configure the default proxy and can be scripted, as demonstrated in this example, as a banner ad buster. Not without some risks, the configuration is downloaded either based on a DHCP option or a DNS based web server (using the prefix “wpad.” and the system FQDN).

With Automatically detect settings enabled, you will also see the following requests:

Option 53: DHCP Message Type = DHCP Inform
Option 61: Client identifier
    Hardware type: Ethernet
    Client MAC address: 00:18:xx:xx:xx:xx (00:xx:xx:xx:xx:xx)
Option 12: Host Name = "laptop"
Option 60: Vendor class identifier = "MSFT 5.0"
Option 55: Parameter Request List
    1 = Subnet Mask
    15 = Domain Name
    3 = Router
    6 = Domain Name Server
    44 = NetBIOS over TCP/IP Name Server
    46 = NetBIOS over TCP/IP Node Type
    47 = NetBIOS over TCP/IP Scope
    31 = Perform Router Discover
    33 = Static Route
    249 = Classless static routes
    43 = Vendor-Specific Information
    252 = Proxy autodiscovery
End Option

Replying to either the DHCP Discover, Request, or Inform messages specifying the Proxy autodiscovery option will inform Windows of the required WPAD URL:

Option 53: DHCP Message Type = DHCP ACK
Option 1: Subnet Mask = 255.0.0.0
Option 3: Router = 10.1.0.1
Option 6: Domain Name Server
    IP Address: 208.67.222.222
    IP Address: 208.67.220.220
Option 51: IP Address Lease Time = 15 minutes
Option 54: Server Identifier = 10.1.0.1
Option 252: Proxy autodiscovery = "http://ap.coova.org/wpad.dat"
End Option

With the option specified, and since DHCP takes priority over any DNS based WPAD source, Internet Explorer happily takes the configuration. Even though my Mac sends the following in a DHCP Discover message:

Option 53: DHCP Message Type = DHCP Discover
Option 55: Parameter Request List
    1 = Subnet Mask
    3 = Router
    6 = Domain Name Server
    15 = Domain Name
    112 = NetInfo Parent Server Address
    113 = NetInfo Parent Server Tag
    78 = Directory Agent Information
    79 = Service Location Agent Scope
    95 = Lightweight Directory Access Protocol
    252 = Proxy autodiscovery
Option 57: Maximum DHCP Message Size = 1500
Option 61: Client identifier (6 bytes)
Option 51: IP Address Lease Time = 90 days
Option 12: Host Name = "iMac"
End Option

The Mac does not use the returned Proxy Autodiscovery option, at least not with Safari.

Still, interesting stuff… and could pose a problem if you are at a hotspot and your Windows laptop auto-configures a proxy server that is not accessible in the walled garden!

Happy new year!

To bring in the new year, there are new features already live in CoovaAAA and some interesting CoovaChilli development in progress. As mentioned on the mailing list, CoovaAAA now has the following features:

• basic session history graphing
• basic access point bandwidth graphing
• downloading of session data
• access point monitoring notifications
• “open access” MAC address authentication
• updated CoovaAAA Desktop application

The bandwidth graphing and monitoring notification features currently require CoovaChilli. The “open access” feature requires MAC address authentication and currently supports CoovaChilli and Colubris access controllers.

Above, you can see the settings for an access point. If you are using a supported access controller, then the type and basic settings (like reversed accounting) have likely been auto-detected. Note that the bandwidth graph and monitoring alerts are only available currently for CoovaChilli.

Open Access, with Accounting

With open access enabled in CoovaAAA and MAC address authentication configured in the access controller, visitors to your HotSpot are automatically authenticated and given Internet access. Give access to anybody, anonymously, by adding the special anonymous realm to your Allowed Realms, as shown below.

The user experience is no different from an open access point, but you benefit from session and usage accounting.

Graphing & Downloading Sessions

CoovaAAA now has graphs! For the simple session summary graph, JFreeChart is being used - an excellent and easy to use open-source charting library. The graph shows the number of sessions and minutes per day, based on the start time of the session.

This is perhaps not always ideal since sessions can last longer than a day and you don’t necessarily want to graph all that time in one day. Above is an example of the graph showing a mixture of access controller types. Of course, if the access controller doesn’t support RADIUS accounting, like many commercial WPA Enterprise routers, you will not see any minutes for those sessions.

In the same window, you can now download the selected sessions in a comma separated value (CSV) data file. This data file contains Session ID, Username, Realm, Status, Start time, Stop time, Duration, Bytes down, Bytes up, Device, Location, and other attributes taken from RADIUS.

Want to see the overall usage in CoovaAAA so far this month?

(Note: A time-zone conversion issue has been noted where the graph is showing, for example, some sessions on December 31, when the graph should start on January 1st. The system time-zone is US Pacific, my profile is set to Central European Time.)

Graphing Access Point Bandwidth

CoovaChilli can be configured to authenticate itself as an Administrative-User (indicated in the RADIUS Service-Type attribute). This provides a convenient way for chilli to retrieve configuration settings from the RADIUS back-end. Using this RADIUS session, chilli sends global accounting of all running sessions back to the RADIUS server. These accounting requests can be, as they are in CoovaAAA, used for monitoring purposes and/or bandwidth graphing.

For the data collection and graphing, JRobin is being used - providing a pure Java RRD (round-robin database) similar to that RRDTool.

CoovaChilli Development

Last year, I mentioned some interesting features for CoovaChilli which are now in development. To summarize, a number of people in the forum have asked about less restrictive “splash page only” features - where visitors have full Internet access, but with an initial splash page when visitors are web browsing. To provide this, chilli will have a new internal state (not surprisingly called splash) whereby visitors who are otherwise authorized are redirected to a splash page - either the chilli uamserver setting or a session specific URL.

There will be two ways to put a session into this state: 1) with a RADIUS ChilliSpot-Config=splash attribute in the Access-Accept (during MAC authentication, for instance), and 2) using the chilli_query command line utility. To ensure the visitor has been to the splash page, chilli will still require a (re-)authentication via RADIUS to resume full authorized access. To some, it may seem over-kill to require a RADIUS authentication for a splash page acknowledgment. However, doing it this way provides a bit of proof of the acknowledgment in the back-end while also giving the opportunity to reconfigure session provisioning parameters.

Per default, when you use MAC authentication with chilli, an Access-Reject means that the visitor failed to authenticate by MAC address, but still may proceed to the captive portal where they can login. There will be a new option, called macauthdeny, to have chilli ignore all traffic from visitors given an Access-Reject during MAC address authentication - thereby black-listing the device.

Other Development

On a completely different topic, I have recently been working with Diameter and came across this JavaDiameter project. The library provides a very nice pure Java (except for the optional JavaSCTP layer which does use a JNI library) Diameter stack. The API is rather perfect for building a RADIUS/Diameter gateway using JRadius!

There is a new version of CoovaAAA deployed! The highlights:

• Ability to create access policies defining time and data limits
• Share with users or entire realms based on a policy
• Generate a limited number of access codes based on a policy
• Support for CoovaChilli/Chillispot data limits based on a policy
• Stopping stale sessions when the NAC reboots
• Updated Facebook and new general use captive portal
• Bug fix concerning WPA-only option

Access Policies

Access policies define how access is to be provisioned. With this release, you can set the amount of access time and/or the data limits granted in a certain time frame. For instance, a policy might be for 2 hours of access, with a data cap of 10G, to be used within 24 hours. Additionally, the policy can be configured as recurring; for instance, a policy for 2 hours per any 24 hour period. Use policies to limit the access of individual users or entire realms you are sharing with. This includes Facebook users when using the Facebook captive portal.

This screenshot shows the look-and-feel of the Facebook embedded version and how users can individually be configured with an access policy. Similarly, in the next tab, Share with realms, you can configure entire realms with an access policy, specifying whether or not the limitation is for the entire realm (as in everybody has to share the same 2 hours) or if it should be per user (where a new Allowed User is added with the access policy).

Access Codes

In this release, you are able to create 10 access codes based on a access policy of your own. The limit is there while the feature is in beta. When you create an access code, you are basically creating your own usernames and passwords linked to your access policy and network (your own access points). Below, showing the standard look-and-feel, you can see the new Access tab in the manager application and some sample access codes.

Notice how access codes are considered under the realm “code” in the system. This is to not conflict with the default realm of users (i.e. the coova.org realm). Ultimately, when logging in to a network you need a username and password (”credentials”). For the access codes, this means the username, in theory, must be prefixed with this code realm according to RADIUS specification. That gets pretty technical. But, the new Facebook and general use captive portal in CoovaAAA makes it easy by providing a separate login dialog for both users and codes, as shown below. When logging in with an access code, the appropriate realm is automatically prepended.

Captive Portals

The Facebook captive portal was updated. Some adjustments were required as Facebook no longer enforces a login before viewing an application.

Which is nice - since now it is easier to put a login box for Coova-enabled user and access code logins for when the visitor is not a Facebook member.

With the same login box features of the Facebook application, there is now also a general use CoovaChilli captive portal login application. Similar to the embedded captive portal of CoovaChilli and CoovaAP, but this hosted version will be expanded and updated more frequently. It can be used with your own RADIUS back-end or take advantage of the features offered through CoovaAAA - including OpenID authentication (enabled as an option).

Learn more about this newest addition to the Coova hotspot development kit. I’m thinking of calling it this as everything Coova can not only be used as a whole, but also as bits and pieces. With more and more bits and pieces coming in the form of software, tools, resources, and services! If you find any problems or have suggestions, let us know in the forum.

There are new releases to announce, first of all. CoovaChilli version 1.0.11 was released with some bug fixes, leading to a new version of CoovaAP, released as 1.0-beta.7d, to include the new Chilli. Last, but not least, CoovaAAA was updated, as was the Coova HotSpot Facebook application, to work with the new Facebook Pages. Now, you can use CoovaAAA along with either CoovaAP or CoovaChilli to authenticate Wi-Fi HoSpot visitors based on your Facebook Page fans!

Facebook Profile HotSpot

As mentioned, once you add the Coova HotSpot application to your profile you can then configure your Coova-enabled Wi-Fi HotSpot to automatically allow you and your friends to reach the entire Internet - while all other visitors are only allowed access to the walled-garden. It’s a great way to share your Wi-Fi with those you know and for those you don’t know to introduce themselves. Introducing yourself first, after all, is the social thing to do, right?

Facebook Page HotSpot

Facebook introduced pages that you can create for your restaurant, hotel, cafe, club, or just about any other business or organization. Instead of having Friends, like your Profile, Pages allow users to self-proclaim themselves as “Fans” - and gives the page owner a convenient way to communicate with their fan-based. The Coova HotSpot application now supports Pages in addition to Profiles as being the “owner” of a HotSpot. Just like how the Profile HotSpot allows only you and your friends Internet access, the Page HotSpot will automatically login the Admins and Fans of the page. Follow the directions for setting up your HotSpot, but use the “Page ID” instead of your “Profile ID” as the HotSpot owner.

How To Setup

The first step is always to add the Coova HotSpot application to your profile. You need this in your profile before you can setup or access a HotSpot using the application. Before setting up a HotSpot, you will also need to sign-up for a Coova account. Link your Facebook profile to your Coova account by clicking on the Coova Hotspot application link on the left navigation bar in Facebook. Login to the embedded CoovaAAA manager once to link the accounts. The next time you visit the manager, you will be automatically logged into Coova.org.

Next, proceed to create your page and also add the Coova HotSpot application to the page. Configure CoovaAP or CoovaChilli as described in the directions using the Page ID as the HotSpot owner, as explained above, and your personal RADIUS shared secret from your Coova account. Oh, don’t forget to publish your Facebook page!

When you have your page and HotSpot setup, connect to your HotSpot logging in to Facebook as an admin of the page. The first time you do this, you will be given instructions on how to link this page to your Coova account, as shown here:

You’ll notice that the example Facebook page used here was created with name “Cafe Wi-Fi” and this Facebook user account is an Admin of the page (note: the “HotSpot Cafe Wi-Fi” title comes from the Location Name configured in the HotSpot / Location section of the CoovaAP admin interface). This Facebook user is already linked to a Coova account. After making sure the HotSpot is configured with that Coova account’s RADIUS shared secret, link the page to your Coova account by clicking on do this now!. Then, with the HotSpot properly configured and linked to a Coova account, Admin users are automatically logged in:

When a Facebook user, who is not a fan, tries to access the Internet, they will see:

Where the links on the page will take the user to the Cafe Wi-Fi Facebook page - where the user can sign-up as a Fan. Once they do, they will be able to get on-line:

It’s that simple! We will, of course, keep adding features… and suggestions are always welcome in the forum.

Yes, development never stops! There are some new releases to report:

CoovaChilli 1.0.9 has been released. This is largely a bug fix release, see the ChangeLog for details. Binaries for more systems will be available soon.

CoovaAP 1.0-beta.7 has also been released, with the following highlights:

• CoovaChilli 1.0.9
• Facebook HotSpot configuration
• Notes on Upgrading from previous version

As promised, this version allows for easy configuration for the Coova HotSpot captive portal application on Facebook.

My last post was geared toward attracting the network administrators of communities, schools, or companies to come and roam with CoovaAAA. It would be awesome, for instance, if CoovaAAA users could selectively share their networks with the FON community, their classmates at school, or colleagues at work. However, not all of these organizations use RADIUS and those who do are often unwilling to change their setup without strong financial incentives or demands from their users. Which got me thinking, many people these days are creating and linking their communities, colleagues, and friends using on-line “Social Utilities” like Facebook. I have been looking into the Facebook platform and started integrating it with CoovaAAA. The result is turning out better than initially expected!

The Social WiFi Utility

Facebook has an interesting platform. I now realize that it being called a “Social Utility” isn’t just marketing hype. With their API, FBML, FBJS, and FQL technologies combined with the overall friends and network architecture, it is relatively straight forward to create an entire “social networking” application around Facebook or integrate their platform with another. Since CoovaAAA is about managing your WiFi network and sharing it with others, it makes sense to leverage the social network building features of Facebook to create a Social WiFi Utility.

This is made possible with a captive portal application built for the Facebook platform combined with the CoovaAAA authentication services.

The Facebook Application

Facebook enforces that all visitors are members as they are redirected to the Facebook Coova HotSpot captive portal application. Facebook is placed in the HotSpot’s walled garden, so all visitors are able to login and see the owner’s profile - leaving a message or giving a “poke”.

Above is what you see when logged into Facebook, but not a friend of the HotSpot owner. Of course, the owner is always logged in automatically, so are friends, as shown below.

The access point owner must have a Coova account (linked to their Facebook profile). Visitors don’t need a Coova account, but also benefit from having one.

With your Coova account linked to your Facebook profile, you are able to see your usage and perhaps manage your own Coova HotSpot - all from the embedded application.

Getting Started

The latest release of CoovaChilli or CoovaAP is what is needed running on your router - be it Linux or Linksys (and some others).  You will find the documentation in the wiki and you are able to get help in the forum or IRC (#coova at freenode.net).

(updated November 5)

There are at least two meanings of WiFi Roaming. First, there is the physical hand-over of a client device from one access point to another - like perhaps in a mesh network. The other, and the one this article is about, refers to authentication, authorization, and accounting (AAA) roaming. Access controllers, like CoovaChilli, authenticate users and provide session usage accounting using RADIUS. Through the RADIUS server, access is provisioned with or without session time or usage limitations and session statistics are collected.

RADIUS Roaming, or Realm-based Roaming, is a feature of the RADIUS protocol whereby messages are forwarded by proxy to a remote 3rd party for processing based on a Realm. A realm in RADIUS is like the domain name in an e-mail address. It specifies the Home Provider of a user identified by a username and is usually formatted in one of two ways: as a prefix realm (e.g. realm/username), or like an e-mail address with a suffix realm (e.g. username@realm).

RADIUS Roaming

In CoovaAAA, when you allow the realm coova.org access (on the Sharing page of the web interface), you are allowing other Coova users to get access using your network. It is also possible to grant login permission to other realms using remote RADIUS servers. If you have a user community (with a RADIUS server) and want to enable roaming with coova.org, contact us! It’s a great - and free - way to share with the community you already know; you’re own.

If your RADIUS server does not support EAP protocols, or they are just too cumbersome to setup, CoovaAAA can help by terminating the EAP-TTLS tunnel and doing proxy for the “inner” tunneled authentication. This way, you can still get the benefits of WPA Enterprise / 802.1X without having to upgrade or reconfigure your current RADIUS installation.

When using EAP-TTLS based protocols, you essentially establish a SSL connection (over UDP) directly to the RADIUS server. Over this tunnel, “inner” authentication can be performed using the user’s true username and password. The “Supplicant,” or client software (the internal Macos X Internet Connect or SecureW2 for windows, for instance) establishes this connection and verifies the certificate of the RADIUS server it is talking to. If trusted, then authentication is performed.

RADIUS Accounting

RADIUS provides a means of accounting for the time and data consumed by users. It does this following various RFCs in order to be compatible with other vendors of similar products. Unfortunately, the meaning of what a client has sent versus what they received (in the form of Input or Output RADIUS attributes), can be reversed depending on vendor and configuration.

To maintain consistency, CoovaAAA now allows the option Reverse Accounting when editing an Access Point - which defaults to enabled for compatibility. When proxying, CoovaAAA will send the correct values (reversing them if required) per RFC 2866. For more information, see the CoovaAAA RADIUS requirements.

CoovaChilli Accounting

Yes, the default accounting in CoovaChilli is reversed from ChilliSpot and now less-than RFC compliant. This was done, believe it or not, for compatibility reasons. However, since the first “coova” version, accounting is reversible back with the swapoctets option. If you use the swapoctets option with CoovaAAA, be sure to un-check the Reversed Accounting option for the Access Point.

New releases of CoovaAP and CoovaChilli are available for download.

New in CoovaAP Firmware version 1.0-beta.6:

• Upgraded wl, nas, and nvram packages
• Upgraded WiFiDog with patch (for CoovaAAA compatibility)
• Default interim interval and secondary server options in HotSpot / RADIUS
• Upgraded coova-chilli to 1.0.8
• Fixes for problems reported in beta.5

New in CoovaChilli version 1.0.8

• See the ChangeLog

You may recall a demo I linked to a few months ago in a past article. It is a Google Web Toolkit (GWT) based application - which means it is completely HTML, JavaScript, and CSS based on the front-end - for managing configurations on a CoovaAP device. Using JSON and RPC style callbacks, the application fetches the router configuration and the user interface screens to edit it. It can then push a new configurations to the same small light-weight CGI application, in this case, written in C. The only real bummer about using GWT is that, although very good, it doesn’t necessarily support all browsers (Konqueror, from what I hear) - and the generated application files, even when compressed, can be a bit large for the smallest of devices (about 400K).

I figured the solution to those problems would be to use Adobe Apollo - now named AIR for Adobe Integrated Runtime. AIR is a framework that allows you to build desktop applications using web technologies. I thought it should be easy enough to use with GWT. And it was! With a few modifications to the GWT code to detect if it is using AIR and to allow configuring of the RPC host, the demo is now available as a desktop application!

Of course, you have to install AIR first. This is required on any desktop running the application. For developers, there is also the AIR SDK which is needed to create an AIR package. AIR only runs on Windows and Mac - hopefully they will eventually support Linux! Setting up the AIR SDK, at least on a Mac, was simple. Just unpack the SDK into any directory and put the bin directory in your path (in your Terminal window, use export PATH=$PATH:/path/to/AIRSDK/bin added to your ~/.profile).

To begin, I started with an example. I then proceeded to setup the icons - very important - It has to look good! I created the suggested 4 (128px, 48px, 32px, and 16px square) to replace the Adobe defaults. Next, created the application.xml file following their example.

 <?xml version="1.0" encoding="UTF-8"?>
 <application appId="com.coova.CoovaAP" version="0.0" 
    xmlns="http://ns.adobe.com/air/application/1.0.M4">
        <name>CoovaAP</name>
        <installFolder>Adobe/AIR/CoovaAP</installFolder>
        <description>CoovaAP Router Administration</description>
        <rootContent systemChrome="standard" transparent="false" 
                      visible="true" width="800" height="600">
                www/com.coova.ewt.Home/AIR.html
        </rootContent>
        <icon>
                <image16x16>icons/i16.png</image16x16>
                <image32x32>icons/i32.png</image32x32>
                <image48x48>icons/i48.png</image48x48>
                <image128x128>icons/i128.png</image128x128>
        </icon>
 </application>

Easy enough. But, now I did have to make some modifications to my GWT application. It was designed to only access the server it was loaded from for RPC calls (required by browsers for security reasons). However, with AIR, you do not have these browser limitations. To enable the application to access and configure any device, I adding a GWT login DialogBox - a pop-up asking for the hostname, port, etc - and the following bit of native code to check if it is running in AIR:

 public static native boolean onAIR() /*-{
     return ($wnd.air != null);
 }-*/;

It does a simple check to see if it has the air object in the JavaScript window. The air object is defined in AIR.html - which is just a copy of my standard Home.html for the application. But, this one includes the AIRAliases.js file contained in the Adobe examples (and added to my GWT application’s public source directory). It, among other things, does the following:

In AIRAliases.js:

 var air; if (!air) air = {};

In AIR.html:

 <script src="AIRAliases.js" />

Based on the result of the native method in the GWT code, the pop-up dialog prompts for a RPC hostname and port, as shown below configured to use the demo router (username and password not used in demo).

Other than the new pop-up dialog and the check for AIR, I had to make no other modifications to my GWT application. After rebuilding my GWT application, with www/com.coova.ewt.Home being the output directory in my case, I built the final CoovaAP.air file using the SDK and the command:

adt -package CoovaAP.air application.xml www icons

This produces a completely self-contained desktop version of the GWT web application to work with any remote device, which now only requires the RPC back-end (the CGI) instead of a complete user interface.

Can’t wait to explore what else AIR offers as a desktop runtime - local file access, for example. So far, it looks really nice!

So nice, in fact, I had to make a desktop version of the CoovaAAA Manager!

There is a new version of CoovaChilli in SVN that is getting close to being released as version 1.0.7. There are several fixes and new features, see the ChangeLog for details. One cool feature added is the JSON interface which allows for easy communication for browser based captive portal applications. Meaning, using JavaScript it is possible to use any HTML page as your captive portal landing page just by adding one line of HTML code:

<script id='chillijs' src='http://coova.org/js/chilli.js'></script>

When the page is used as the chilli login page, the script above attempts to load the ChilliController, javascript contributed by Yannick Deltroo (thanks!), and the default login form template. The ChilliController code and default HTML template are hosted by the chilli daemon directly - customizable on a per location basis. For instance, this simlpe captive portal page (picture below) uses CSS to customize the user interface, as does this simple example:

<style>
<!--
#chilliPage {
  border: 1px solid orange;
  padding: 20px;
  margin-top: 20px;
}
#signUpRow {
  display: none;
}
-->
</style>
...
<script id='chillijs' src='http://coova.org/js/chilli.js'></script>

All the elements of the form can be styled individually, or completely turned off like the sign-up link (element ’signUpRow’) in the above example. The coova default landing page uses some simple CSS to produce:

A simple and interactive captive portal page. The ChilliController loads location information (like the location name, “My HotSpot” above), takes care of logging in (using CHAP challenge/response) and periodically checks for login status and session stats, producing:

A captive portal login/status box like this can be easily embedded into any web page! I’m using my .Mac home page … you get the point.

But, this version of chilli still needs some testing… and to be released soon. If you have a computer running Linux with two network interfaces (doesn’t have to be WiFi, you know), give it a try! Bring your feedback to the forum.

There is a new version of the free CoovaAAA service now running. You are now able to selectively configure your account in general, and then specific devices, for MAC Address Authentication! Of course, this only works with supported access controllers and configurations - so, for only CoovaChilli (or ChilliSpot) and WiFiDog captive portals solutions - possibly others. This feature does not work for WPA Enterprise, and not needed as most clients will likely auto-connect with your configured account information.

How to configure for MAC Authentication

When logged into https://coova.org/, edit your Security Preferences to include Allow MAC Authentication, as shown below:

Only if this user-level option is set will any device owned by the you be allowed to authenticate automatically.

Configuring your device

You may already have some devices associated with your account. Find your device which you added by logging in, using WPA or embedded captive portal configured for coova.org AAA, at least once before.

Click on edit and then select the Allow MAC Authentication option. Setting this option means that your device will auto-authenticate using RADIUS at hotspots configured to perform MAC authentication with CoovaAAA services.

You can’t currently add client devices manually. That is a big limitation, I know, but some thought is required to prevent abuse. True, you can spoof RADIUS, but don’t want to make it easy to harvest arbitrary MAC addresses. It requires some thought and anti-abuse measures. Suggestions, comments, and help requests are welcomed.

Note: Using this feature, of course, does not improve your account security! But, for many, a risk they are willing to take for the convenience.

The WiFiDog project offers an excellent and highly customizable captive portal solution. Used by many free community networks and increasingly for commercial and pre-paid WiFi access providers, it offers an access controller application (in the access point) and a PHP based captive portal web application. Whereas ChilliSpot, also an access controller, does not offer much in the way of captive portal other than a generic perl CGI program. As an access controller, WiFiDog and ChilliSpot do similar functions. However, they differ in fundamental ways. For instance, Chilli relies on RADIUS in the access controller and does DHCP internally where WiFiDog requires it’s accompanying captive portal application - RADIUS is done in PHP by the back-end - and does not control DHCP. WiFiDog uses iptables where Chilli does it’s own packet switching. There are many differences as WiFiDog relies more on the web based back-end and Chilli focuses on RADIUS and features in the access controller.

Bringing some of the lesson learned with Chilli, some patches are now available for testing to: improving RADIUS support, add WISPr XML, and introduce MAC Authentication to the WiFiDog suite.

RADIUS improvements include the use of Called/Calling-Station-Id providing MAC addresses, use of Acct-In/Output-Gigaword for accounting roll-over, Acct-Session-Id added to Access-Request, and support for Session-Timeout.

Added WISPr XML support to assist devices and smart-clients in seamless authentication. The embedded XML provides instructions on how to login to non-browser based applications running on the client device. Usernames presented to WiFiDog will be parsed for a realm - which is then used by WiFiDog as the network name. So, for allowing a realm to roam, a “network” can be created with a RADIUS authenticator, for example.

MAC Authentication is being done using the pcap library (for now) and watching for DHCP replies. It is activated by specifying the MacAuthRealm configuration option in the wifidog.conf specifying the WiFiDog “network” to use for authentication and (currently) requires that the network is configured for RADIUS authentication in WiFiDog.

The changes are provided to (hopefully) raise the standards of WiFiDog with respect to RADIUS and WISPr generally, but are also required for use with CoovaAAA - requiring more standardized RADIUS and access controller feature set. Of course, the patches are provided under the Gnu Public License and your testing and use is encouraged! Bring your questions and comments to the community. Enjoy!

For fun, here is a break-down of the devices (WiFi or Ethernet NIC) seen by CoovaAAA grouped by manufacturer based on IEEE OUI assignments. Some companies are listed multiple times because they have been allocated multiple blocks of MAC addresses - sometimes under slightly different names in the OUI database.

With the newest release of CoovaAP, some new features in Chilli are demonstrated in combination with RADIUS to allow OpenID based authentication. If you are not yet familiar with OpenID, it is a distributed authentication protocol whereby you use a URL for your identity. This URL might be your LiveJournal page, from your MyOpenID account, or any page you desire. Once logged in, your federated identity is valid across many websites. Now it can be used for WiFi access too.

Above is the OpenID login form in CoovaAP’s embedded captive portal. Instead of a traditional username and password, the user’s OpenID URL is entered. When the form is submitted, the OpenID is sent to the RADIUS server (as a username). The RADIUS server, knowing that OpenID was turned on in access point (see below), will discover the OpenID authentication server for this URL and update the user’s (session specific) walled garden before redirecting the user to their OpenID server to log in and grant permission (trust) to Coova.org.

To give an example, I signed up with LiveJournal and configured my personal home page with the following HTML:

<html>
<head>
<link rel="openid.server"
  href="http://www.livejournal.com/openid/server.bml">
<link rel="openid.delegate"
  href="http://wlanmac.livejournal.com/">
...

This will allow me to use my own URL while actually using my LiveJournal identity to log in everywhere. Now, when I log in to the captive portal with my homepage URL, I get authenticated at LiveJournal. Here’s a sample of what their confirmation page looks like after logging in, if not already.

Once permission is granted for this “calling” URL, in this case at coova.org, you are redirected back and logged in to the access point.

Using OpenID with Coova

CoovaAP version beta-1.5 or newer is required for this setup. The HotSpot RADIUS settings must also be configured (as per default) to coova.org. If you have a CoovaAAA account, then use those RADIUS settings. Otherwise, the “coova-anonymous” shared secret can be used.

Using the web interface, configure the HotSpot RADIUS settings making sure Allow OpenID Authentication is Enabled, as shown here. On this same screen, you can now also configure the default session time and idle timeout - to be used when not otherwise set by RADIUS. Save and apply your changes.

With OpenID enabled and using the internal captive portal, a link to the OpenID login form is placed in the default login page. The templates for these pages can be customized in HotSpot / Portal of the web admin.

If you are using your CoovaAAA RADIUS settings, then you will see OpenID sessions, along with everything else.

Well, that’s it! Enjoy… and let us know how it goes.

New releases of CoovaAP and CoovaChilli are available for download.

New in CoovaAP Firmware version 1.0-beta.5:

• Stability patch from OpenWrt forum (thanks to solca)
• OpenID Authentication option in HotSpot / RADIUS
• Default session time and idle timeout options in HotSpot / RADIUS
• Some fixes and updates

New in CoovaChilli version 1.0-coova.6

• See the ChangeLog

Many people think that WiFi will be everywhere sometime soon. I agree, but wonder in what form, or rather, how many forms. Muni wireless projects are happening all over the place, as they should. There are substantial benefits for public infrastructure - providing private networks for city departments and emergency services. But, what about public access? Given that politics is involved, I somehow don’t think ‘anonymous’ open access to WiFi will last long, not on that scale. Just one high-profile law suit of a minor or transient downloading illegal porn or committing other crimes over the Internet and there’s the end of that. And what about CALEA? Can a wire-tap be targeted and guaranteed without being certain of IP or even MAC address? Then there is also the constant threat of the so-called Evil Twin and the harvesting of MAC addresses, usernames and passwords.

The need for 802.1X

Wireless security. It just sounds right. And it is right. Particularly in certain circumstances. It’s when you’re talking massive coverage through a city-wide mesh or in the homes of residents. Many people already use some kind of wireless security in their homes, usually WEP (not good) or WPA Personal (better). Others intentionally leave their access points open as a way of sharing or just don’t know any better. Regardless, I believe people want security and the ability to share with friends and community. This is possible by passing around WEP or WPA-PSK keys, made easy with the help of software. But, perhaps not well suited for the muni or large scale community.

For ubiquitous WiFi access networks, the solution lies in WPA-Enterprise and 802.1X. Wireless security using standard technologies; takes advantage of inter-community roaming and provisioning features found in access controllers using RADIUS; and very likely to be compatible with WiMAX networks down the road.

What makes 802.1X so great? The answer can get technical, but boils down to 1) robust wireless security, 2) centralized access provisioning and configuration, and 3) being able to ‘authenticate’ the network before revealing any username or password (similar to how SSL works on secure websites). Then, why don’t people use 802.1X more? First of all, people do! At work, on campus, even at commercial and public hotspots. Perhaps main-stream adoption is slow because Windows doesn’t make it overly easy to configure - certainly not as easy as on a Mac. But, that might soon change as cross-platform “smart clients” become more widely available and easy to use.

The need for captive portal

Ok, wireless security is great, but there is a purpose to having a captive portal - almost always with an “open” access point (no wireless security), though not necessarily. The portal is important to communities and venues like cafes, hotels, airports, and so on, not only to sell access, but to give useful location specific content. In many of these cases, the threats of the open access point are mitigated by the fact they are in public places - people doing something they shouldn’t be tend to be suspicious in other ways and draw attention (as the theory goes). Additionally, some commercial WiFi products can help venue owners detect and deal with rogue access points and other security threats. Captive portals applications can be made relatively safe for casual use. And, do visitors of such places really expect their traffic to be secure? I would guess the expectation of security is less than when connecting at home, work, school, or the city mesh - places where people feel comfortable and networks they use every day.

That’s not to say having a captive portal, or “walled garden,” isn’t beneficial even when using 802.1X. It can provide instructions on how to access the Internet using an existing account (of this or a roaming network, or voucher code) and how to obtain one if new to the network. Also to give general information about the community, the project, maps of the area, and where to find help.

Community awareness

Large scale WiFi networks should, of course, service their communities in a responsible way. I believe doing so is part technical: wireless security, part social: not promoting “all WiFi is good”, part legal: not a safe haven to do all the things you don’t want to do from home, and part business: don’t ruin the commercial and community WISP.

What is still needed is the ability to seamlessly access your home and community WiFi without having to compromise individual security. At the same time, being able to selectively share and use the access of others. Using your own credentials for 802.1X, in friends’ homes or in the city mesh, or captive portal in the community centers, cafes, hotels,… places you “trust.” As previously noted, we still need client software to balance security with ease-of-use, and that is coming. But, we also need for communities to be built and a public roaming network to be established. One step at a time.

Well, there’s one opinion. What’s your’s? Leave comments or join us in the forum… we are particularly interested in hearing from those responsible for networks with an interest in community roaming.

In a previous post, the idea of using the Google Web Toolkit to create a new kind of embedded web administration interface for devices was discussed. I continue the discussion by providing some examples and a working demonstration of the user interface.

The interface is designed, in this case, to be the administrative web console of a OpenWrt-based firmware. As such, it is a tool to configure (linux) system parameters and files - which may be different depending on the underlying system. For instance, the WhiteRussian branch of OpenWrt use NVRAM settings while Kamikaze uses the new UCI Configuration.

Working with XML

The application in this example uses XML to define the system configuration and also to define the user interface to edit this configuration. XML is well suited for this purpose and offers many benefits, including:

• Easy to read and edit by hand
• System independence and interoperability
• Transformed into other formats using a structured language
• Excellent open-source libraries, tools, and resources

The well-formed structure of the XML resources are converted into JSON objects by a CGI program running the server-side of the application. The GWT interface exchanges JSON objects with this CGI back-end to load or save data.

Defining system configuration

The GWT-based user interface is designed as a configuration editor. The configuration itself is stored in XML as specified in the sysconfig DTD. The DTD defines how a system is configured and is used for basic syntax verification. Here is a portion of the “config.xml” system configuration based on this specification:

<sysconfig>
  <system>
    <settings boot_wait="true" hostname="Coova"/>
  </system>
  <network>
    <interface id="loopback" proto="static" .../>
    <interface id="lan" proto="static" .../>
    <interface id="wan" proto="dhcp" .../>
  </network>
  ...
</sysconfig>

The XML is transformed into JSON by the CGI program when sent to and stored by the GWT application (as a JSONObject), as shown in the “Status / Config Tree” tab of the demo.

Defining the user interface

The user interface screens are defined in XML based on the cap-ui DTD. The portion that builds the systems settings screen to configure the above XML segment is as follows:

<cap-ui>

  <menu name="System">

    <submenu name="Settings">

      <inputset name="System Settings" object="system.settings">

        <input label="Host Name" key="hostname">
        </input>

        <input label="boot_wait" key="boot_wait">
          <option name="Enabled" value="true"/>
          <option name="Disabled" value="false"/>
        </input>
        ...
      </inputset>
      ...
    </submenu>
    ...
  </menu>
  ...
</cap-ui>

Configuration transformations

Taking the XML configuration and using it to set the underlying system configuration is done using XSLT. Transforms take the XML and produce scripts for WhiteRussian (example) and Kamikaze (example), the output of which is shown in the “Status / Config Files” tab of the demo.

The demo

See an on-line demonstration of the user interface using something similar to the above configuration. Please, keep in mind it is still a work in progress and not all the screens and dependencies are defined. The configurations transforms are also incomplete - as is the UCI configuration of Kamikaze.

If you want to help out, come join the forum! (when your done helping out OpenWrt)

If you have been in the forum, you probably already know. But, Coova has launched a new RADIUS AAA service to complement Coova-Chilli and CoovaAP firmware.

About the service

CoovaAAA provides a flexible RADIUS authentication, authorization, and accounting engine designed to make hotspot management easy for users, while also giving them complete control. Users are able to create an account, which provides them with an individual “shared secret” to use when configuring an access point supporting RADIUS authentication — using captive portal or WPA Enterprise (802.1X).

Once signed up and have an access point configured for CoovaAAA, log into the captive portal or WPA network with your Coova.org account. From then on, you will see the AP associated with your account in the portal. You can then share your network with the entire Coova.org community or select individual members. Find members by username or e-mail address, or send an invitation if not already registered.

About the technology

CoovaAAA is built on a highly flexible framework using JRadius along with FreeRADIUS. The main portal is a Java application using Hibernate, Spring, Acegi, XSLT, and many other technologies. The “Manage” section of the portal is an integrated GWT application.

much, much more to come…

JRadius is a project I started to not only address the need for a Java RADIUS client capable of EAP-based authentication, but for a Java framework for processing RADIUS authentication and accounting through a server front end like FreeRADIUS. Why? Well, for several reasons. First, I primarily had Java programmers. But, also because Java offers a lot in terms of portability and integration with other Java components and systems. This article will help point you in the right direction to get up and running with JRadius in both the client and server context - there will be more articles and wiki documentation to come.

Using JRadius with FreeRADIUS

The first thing you need is a FreeRADIUS server with the JRadius module. Instructions on how to do this are here, in the wiki. The JRadius module, rlm_jradius, is what links the FreeRADIUS server to the JRadius server. Using pooled connections, requests are taken out of FreeRADIUS and passed on to JRadius for processing. The basic structure of a JRadius handler looks like:

public class MyHandler extends PacketHandlerBase {
public boolean handle(JRadiusRequest request) {
AttributeList ci = request.getConfigItems();
RadiusPacket req = request.getRequestPacket();
RadiusPacket rep = request.getReplyPacket();
String u = (String)req.getAttributeValue(Attr_UserName.TYPE);
…

}
}

From within the JRadius Java server, you are able to do just about everything any other FreeRADIUS module can do. This includes adding, removing, or altering attributes in the request, the reply, or the internal FreeRADIUS “config items” attribute list. The latter is used within FreeRADIUS - often using FreeRADIUS internal only attributes - to control the state and behavior of the request.

AttributeList ci = request.getConfigItems();
ci.add(new Attr_UserPassword("password"));

For instance, to give FreeRADIUS the plain text password of a user (to be used by FreeRADIUS during actual authentication), you might have the above in your authorize JRadius handler.

Running JRadius Server

To get your handlers up and running, you need a JRadius server. Instructions on how to build and get an example server running is found in the wiki. You can easily build from the JRadius SVN using Maven and Ant. Doing mvn install will setup the dependencies and create jar files in the typical target directory for core (core JRadius client and server), dictionary (attribute dictionary), extended (JRadius classes that require the dictionary), and example (a couple examples). Using Ant by doing ant dist will create just 2 jars in the dist directory - jradius.jar and jradius-dictionary.jar, where the former contains everything minus the dictionary. To summarize the steps in getting the JRadius example server running:

svn co http://dev.coova.org/svn/cjradius/
cd cjradius
ant dist
ant run-example

You can find the example source code in the java/example directory which can be extended to suite your specific needs.

Using JRadius Client

The Client API is simple and able to do a variety of authentication protocols - including PAP, MSCHAPv2, EAP-MD5, and EAP-TTLS/PAP. JRadius can be integrated into any Java authentication scheme. For instance, it has been used with Jive Wildfire and Shibboleth.

Development and Support

For questions, suggestions, bug reports, patches, and the like; I have created a JRadius Forum.