TinyRadius: Java Radius library

TinyRadius is a simple, small and fast Java Radius library capable of sending and receiving Radius packets of all types. It is released under the terms of the LGPL.

SourceForge Project Overview | JavaDoc API documentation | Download current release

What you can do with it:

• send and receive Radius packets (Access-Request, Access-Accept, Access-Reject, Access-Challenge, Accounting-Request, Accounting-Response and others) from within your Java application
• use PAP and CHAP as authentication types for Access-Request messages
• attach arbitrary Radius attributes to the packets employing attribute names read from a dictionary file
• send and receive Radius packets with "Vendor-Specific" attributes

What you cannot/should not do with it:

• set up a complex Radius server (please use FreeRadius or JRadius)
• connect the server to a user database without writing Java code (this library is ment to be plugged in applications and not to be used as a stand-alone server)

TinyRadius comes with small sample applications which show how to integrate it as a Radius server and a Radius client.

What are the requirements?

• TinyRadius works well and is tested with JDK 1.1 through 1.6. I recommend using at least JDK 1.4.
• You need Apache Commons Logging to compile and run TinyRadius. This small library is included with the TinyRadius release.

EXAMPLE 1: Authentication made easy

If you do not need to set special attribute values, you can just use the method authenticate() from the RadiusClient:

RadiusClient rc = new RadiusClient(host, sharedSecret);
if (rc.authenticate(userName, password)) {
	...

EXAMPLE 2: Sending an Access-Request with multiple attributes

1. Create a RadiusClient object with the host name and shared secret of the Radius server you wish to contact. You may set additional details (port numbers, for example) using methods of this object.

RadiusClient rc = new RadiusClient(host, shared);

2. Create the Access-Request Radius packet. Pass the user name and password in the constructor. The User-Name attribute will be added on construction of the object, while the User-Password attribute (PAP) or the CHAP-Password and CHAP-Challenge attributes (CHAP) will be generated when encoding the packet because the request authenticator of the packet is required to encrypt the password.

AccessRequest ar = new AccessRequest(user, pass);
ar.setAuthProtocol(AccessRequest.AUTH_CHAP); // or AUTH_PAP

3. Set further attributes. Note that TinyRadius resolves the attribute type from the given type name and that it converts the IP address and the name of the constant (Login-User) to the right values. Please also note how the Vendor-Specific (WISPr) sub-attribute "WISPr-Location-ID" is set. This call results in the creation of a Vendor-Specific attribute with the proper vendor ID and the addition of a sub-attribute to this attribute.

ar.addAttribute("NAS-Identifier", "this.is.my.nas-identifier.de");
ar.addAttribute("NAS-IP-Address", "192.168.0.100");
ar.addAttribute("Service-Type", "Login-User");
ar.addAttribute("WISPr-Location-ID", "ger,de.sample-location");

4. Send the packet and receive the response.

RadiusPacket response = rc.authenticate(ar);
if (response.getPacketType() == RadiusPacket.ACCESS_ACCEPT) {
	...

EXAMPLE 3: How to implement a Radius server

You need to subclass org.tinyradius.util.RadiusServer. Provide an implementation for the following methods:

String getSharedSecret(InetAddress client);

This method should check whether the passed client is allowed to communicate with the Radius server. If this is the case, it should return the shared secret that secures the communication to the client.

String getUserPassword(String userName);

This method returns the password for the given user. If you have not access to the password (in the case of CHAP) or you need finer control (you want to set attributes for the response packet, for example), you have to override the following method.

RadiusPacket accessRequestReceived(AccessRequest request, InetAddress client);
RadiusPacket accountingRequestReceived(AccountingRequest request, InetAddress client);

Override this methods for fine control about the way Accounting-Request and Access-Request packets are handled. Just return the Radius packet to be sent as a response or null if the request should be ignored.

After implementing your own server class, you can start and stop the server using the methods start() and stop(). For start(), you pass whether the server should listen on the auth and/or the acct port. This method spawns new threads.

RadiusServer server = new MyRadiusServer();
server.start(true, true);
server.stop();

EXAMPLE 4: How to implement a Radius proxy server

You need to subclass org.tinyradius.proxy.RadiusProxy. In addition to implementing the abstract methods from RadiusServer, you have to provide an implementation for the following method.

RadiusEndpoint getProxyServer(RadiusPacket packet, RadiusEndpoint client);

Using the provided client endpoint (containing the client's IP address, the port number as well as the shared secret) you have to decide whether the given Radius packet should be forwarded or if the TinyRadius server itself shall handle the packet.

If you return null, the packet will be dealt with as usual. Otherwise, the packet will be proxied (adding a Proxy-State attribute) to the returned Radius server.

For a complete example, please check the three classes TestProxy, TestServer and TestClient, which can be used to set up an easy proxying Radius infrastructure only with TinyRadius and only using "localhost".

Please do not hesitate to contact me if you have got questions or suggestions.