Developer Notes

From JRadius

The Source Code

The JRadius source code is broken up into several directories.

• java/src/

  Contains the JRadius core classes required to build dictionaries, use the client, and run a bare-bones server. No dictionary is needed to build this code-base.

• java/extended/

  Contains more advanced features of JRadius. When building these classes, the existence of the net.sf.jradius.dictionary JRadius dictionary is assumed in the classpath (built automatically by ant using the build.xml).

• java/example/

  Contains examples of the RadiusClient and JRadius Handlers.

• java/tests/

  Contains Java classes and other resources used for testing JRadius.

• java/applet/

  Contains the JRadius WiFi Client and resources.

The JRadius Configuration File

The JRadius configuration file is based on XML and is parsed by the classes in package net.sf.jradius.server.config. Most of the syntax is described in the example jradius-config.xml.

Chaining Handlers in XML Configuration Files

JRadius uses the Apache Jakarta Commons Chain API for chaining packet and event handlers. The API provides the ability to define and configure (with bean attributes) JRadius handlers, which implement the Command interface, into chains of logic.

For instance, the chain catalog net.sf.jradius.handler.catalog.xml contains, among other things, the following definitions:

 <define name="init-session"  className="net.sf.jradius.handler.InitSessionHandler"/>
 <define name="mon-req"       className="net.sf.jradius.handler.authorize.MonitoringRequestHandler"/>

Handlers are then instantiated and linked into chains, as demonstrated in the example application catalog.xml. The name of the final chain must match the FreeRADIUS entry point the chain is for. (Note: as JRadius evolves with additional RADIUS servers, these "entry points" will be less specific to the underlying RADIUS server.) For instance, below we configure the simple chain for authorize containing only the MonitoringRequestHandler configured to respond (with an Access-Reject) to any request with User-Name "monitoring" or NAS-Identifier "monitoring" with the Reply-Message "Monitoring request acknowledged" to confirm acknowledgment.

 <chain                       name="authorize">
     <mon-req                 name="authorize-mon-req"
                       description="Answers monitoring requests with a reject"
                          username="monitoring"
                             nasid="monitoring"
                      replyMessage="Monitoring request acknowledged"/>
     <init-session            name="authorize-init-session"
                       description="Initialize The Radius Session"/>
 </chain>

For more information on how chains work, see the Commons Chain project documentation and the JRadius classes in package net.sf.jradius.handler.chain.

Session Tracking with JRadiusSession

Within JRadius, a RADIUS request, represented by a JRadiusRequest object, can be configured to be associated with an on-going RADIUS session, represented by a JRadiusSession object. The InitSessionHandler is the default handler which creates and associates JRadiusSessions with JRadiusRequests. The JRadiusSessionManager is responsible for managing all the active JRadiusSessions in JRadius. The JRadiusSessionManager stores JRadiusSessions created by the current SessionFactory and is stored in the session manager based on the hash key(s) provided by the current SessionKeyProvider.

As shown in the example jradius-config.xml file, your own SessionKeyProvider and SessionFactory can be configured using the following syntax (this example configures the default SessionKeyProvider and SessionFactory for all "requesters"):

 <session-manager key-provider="net.sf.jradius.session.RadiusSessionKeyProvider"
               session-factory="net.sf.jradius.session.RadiusSessionFactory"/>

It is also possible to configure the SessionKeyProvider and SessionFactory specific to a particular "requester" (the name of the requester is configured in the FreeRADIUS JRadius configuration, see jradius.conf). In the following example, we are specifically configuring the SessionKeyProvider and SessionFactory for requests sent by requester "example".

 <session-manager    requester="example"
                  key-provider="net.sf.jradius.session.RadiusSessionKeyProvider"
               session-factory="net.sf.jradius.session.RadiusSessionFactory"/>

If there is no specific setting for the requester, the default is used. Session and Event Logging The JRadiusSession interface provides methods to manage log entries for a session. The RadiusLogEntry objects are managed within the JRadiusSession and are meant to be retrieved and modified throughout the various handlers involved with a request. Anywhere in a handler, the following will add a log message to the log entry for the request:

 JRadiusSession session = jRadiusRequest.getSession();
 session.addLogMessage(jRadiusRequest, "Authentication Failed");

Log entry attributes can be set by retrieving the log entry itself:

 JRadiusSession session = jRadiusRequest.getSession();
 RadiusLogEntry entry = session.getLogEntry(jRadiusRequest);
 entry.setType("authentication");

When JRadius has finished processing a request, going through a number of handlers, the server will fire the HandlerLogEvent which gets processed (if using the example configuration) by the HandlerLogHandler event handler. This handler commits all the log entries for the session. However, these log entries still remain with the session object and can be updated (in the post-auth, for example) in another pass through the JRadius server.

When sessions expire in the JRadiusSessionManager, a SessionExpireEvent is sent to the event-handler chain for processing.

Limitations

Java 1.5 is required to build the EAPTLSAuthenticator and EAPTTLSAuthenticator classes because of the required Java SSL library. Though, you can not use CHAP, MSCHAP, or MSCHAPv2 within the tunnel because that requires the challenge to be derived from the SSL key material. The Java SSL SDK does not provide this access. Building with Java 1.4.2 is also supported, just without those classes - the build.xml will exclude them. If you are using Eclipse, you might try deleting them and updating your .cvsignore file.