Writing device modules for the eduroam Configuration Assistant Tool
Here, you will learn everything you need to know!
Table of Contents
Introduction
eduroam Configuration Assistant Tool (CAT) is a user-oriented system helping to configure various wireless devices for eduroam.
CAT database contains information provided by local eduroam admins, i.e. items like supperted EAP methods, trusted RADIUS server names, trusted server certificates, etc.
CAT configurators are device dependant entities (Windows installers, XML profiles, etc.), which carry all institution-depenent information. Such a configurator is created when a user selects his/her
instition, possibly also user group and one of supported devices.
See Glosary for a more detailed description of terms used in this text.
What is a device module and how does it interface with the CAT system?
Device module makes use of information availabe in the CAT database available via the CAT API and produces the configurator file.
The module MUST configure the device for accessing the eduroam SSID and possibly other SSIDs which may have been configured for the gien profile. The module publishes the
set of EAP methods it can support, CAT API compares this to the priotarised list of EAP types
supported by a given profile and returns the most appropriate one. Device module creates a confgurator for this EAP method. If the device requires to be separately configured for WPA2/AES and WPA2/TKIP then the configurator SHOULD configure both forms for the eduroam SSID.
What does the CAT API do for device modules?
Before passing control to the device module, CAT system prepares a few things for the module to use.These include:
- intefacing with the user;
- getting all configuration parameters from the CAT database;
- creating a temporary working directory;
- preapring certificate files and making them ready for stroring in the working directory;
- storing information files in the working directory.
After the device module produces the file, it leaves it in its working directory and passes back its name. CAT API delivers the file to the user.
Directory structure and naming
All device modules reside in the devices directory. Each device module has its own subdirectory.
If a device module requires additional files that will need to be coppied to the working directory,
then these files should be placed in the Files subdirectory of the module directory.
The name of the module directory may be arbitraty, but the name of the module file and the name of the device class must be synchronised. For instance, if the name of the module is TestModule, then it's source file should be called TestModule.php and the name of the class must be Device_TestModule.
Naming is defined in the devices.php file, it is a configuration feature and is irrelevant extermal from the moule point of view.
Device driver code
See the TestModule.php for a working example.
We assume, that you are know how a device installer itself.
If not, then this tutorial will not teach you that. It will only show how to get hold
of parameters that you need to build into your code.
Typically, to produce an installer you need to know:
the certificate of the CA which has signed the RADIUS server certificate,
the names of the trusted RADIUS servers,
the EAP method to be used,
the SSIDs to connect to.
the installer will only work properly for users from one institution and, possibly one user
group, it would be wise if to could display an appropraite warning.
In some environments it is possible to display additional text information (pehaps a list of usage terms), it may be also possible to customise the configurator graphics by adding the institution logo.
All these will be available to the device module.
The device module class must extend the DeviceConfig class, thus obtaining access to all methods provided by this class. Check the documentation of that class for a complete list description of these methods.
The module file must use the global $my_aep_methid variable an set it to to an array listing EAP methid supported by this particular device.
The module must define a writeInstaller(Profile $profile) method which.
The $profile argument will be provided by the CAT API when the decice module is called. Device module can use the $profile
object directly, but we do not recommend it. All useful properties are provided within the device's attributes property.
The device module constructor method (which is defined in the DeviceConfig
module and cannot be redefined) sets
The writeInstaller method must begin by calling
$this->setup($profile).
This is the only iteraction with the $profile object that the
device module must have, but it is entirely hidden by the setup method.
The writeInstaller method must create the installer in the form of a single file in the module.
Glosary
Device:
An operating system instance which covers a group of wireless client devices; it may be just a group of oerating systems like "Microsoft Windows Vista and newer" or "Android smartphones" or "iOS devices"
Profile:
A group of users which share the same network configuration parameters (except for user credentials), thus a profile shares the same supported EAP methiods, the same trusted servers etc. Even if the entire institution needs only one profile it will always be created; configurators are prepared per (profile, device) touple.