com.theorem.radserver3.dmcoaserver
Class SendDMCOA

Object
  SendDMCOA

public final class SendDMCOA

extends Object

Class to send messages to client as described in RFC 3576 - Dynamic Authorization Extensions to RADIUS.

This class is independent of the RADIUSServer class and is run in a standalone mode meaning any process in the current JVM or even another JVM may send a DM / COA message to a client.

Disconnect-Request (DM) messages are sent by the server to try to force a disconnection of a NAS (client). If successful the NAS will also release any resources connected with the client application. The NAS will respond with a Disconnect-ACK or Disconnect-NAK depending on it's success. If a NAS does not understand this message it will discard the packets silently.

CoA (COA) messages typically change data filters. The NAS will respond with a CoA-ACK or CoA-NAK depending on it's success. If a NAS does not understand this message it will discard the packets silently.

Both types of messages share common features. These messages are sent in the opposite direction of normal RADIUS messages. That is to say the communication is from the server to the client. The client must be able to asynchronously recessive disconnect / coa messages at any time. Similarly proxy servers must be able to send the packets in the opposite direction. This latter requirement poses some security risks as data normally considered informational is used as fact, like the NAS-IP-Address attribute. Please see the RFC for more details.

There are a number of identifier attributes used to determine the target NAS and session to locate the particular port to be disconnected. These must be saved from the original authentication and perhaps accounting packets and used in the DM and COA requests so proxy servers can perform reverse path forwarding (RPF) and ultimately NAS equipment can determine the port(s) to reconfigure.

It's expected that the AccessImpl or NASCallBack classes will store attributes extracted by the static method extractIdentfiers(AttributeList aList) and associate them with a particular client or NAS address. A DM/COA message must include these identifier attributes in the request so the client can determine the particular session and apply the request. For example if the NAS identifier attribute NAS-IPAddress and the session attributes User-Name and NAS-Port were extracted for the client they must be returned in the request attribute list.

For the SendDMCOA class to work a NAS must be configured for 127.0.0.1. SendDMCOA proxies the requests to the server as the local host or loopback address. The server uses the request to perform the routing using the known secret for the DM/COA target from it's routing tables. This allows any process or even JVM to send DM/COA messages without being part of the RADIUS server.

Field Summary

static int	RETRIES Default number of retries - 3 attempts.
static int	TIMEOUT Default timeout before retry - 1000 milliseconds.

Constructor Summary

SendDMCOA(int packetType, InetAddress dmcoaTarget, byte[] loopbackSecret)
Constructor to send a COA or Disconnect message.

Method Summary

static AttributeList	extractIdentfiers(AttributeList aList) A helper method to extract all necessary identifying attributes from the original Access-Request and perhaps Access-Response attribute lists.
AttributeList	getAttributes() Get the response attributes.
int	getError() Get the error value reported by the client.
String	getErrorString() Get the error string freported by the client.
int	getPacketType() Get the packet type.
int	send() Sends the DM / COA packet.
void	setDebug(boolean debug) Set debugging on or off.
void	setDebug(boolean debug, String fileName) Set debugging on or off.
void	setPort(int port) Set the DMCOA port number if the standard port number isn't used.
void	setRequestAttributes(AttributeList requestList) Set the request attributes.
void	setRetries(int retries) Set the number of retries before giving up - default is RETRIES - you must specify at least one retry or no packets will be sent.
void	setTimeout(int timeout) Set the timeout - default is TIMEOUT.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

RETRIES

public static final int RETRIES

Default number of retries - 3 attempts.

See Also:

Constant Field Values

TIMEOUT

public static final int TIMEOUT

Default timeout before retry - 1000 milliseconds.

See Also:

Constant Field Values

Constructor Detail

SendDMCOA

public SendDMCOA(int packetType,
                 InetAddress dmcoaTarget,
                 byte[] loopbackSecret)

Constructor to send a COA or Disconnect message.

Parameters:

packetType - One of PacketType.Disconnect_Request or PacketType.CoA_Request.

dmcoaTarget - The DM/COA packet will be sent to the client at this address. This may also be known as the NAS address.

loopbackSecret - This is the secret for the local server NAS at 127.0.0.1 (loopback address).

Method Detail

extractIdentfiers

public static AttributeList extractIdentfiers(AttributeList aList)

A helper method to extract all necessary identifying attributes from the original Access-Request and perhaps Access-Response attribute lists.

Parameters:

aList - Original attribute list from the request or response containing identifying attributes.

Returns:

Attribute list containing all the identifying attributes.

See Also:

setRequestAttributes() for a list of attributes extracted.

getAttributes

public AttributeList getAttributes()

Get the response attributes.

Returns:

Response attribute list.

getError

public int getError()

Get the error value reported by the client.

Returns:

error value.

getErrorString

public String getErrorString()

Get the error string freported by the client.

Returns:

error value.

getPacketType

public int getPacketType()

Get the packet type.

Returns:

packet type.

send

public int send()
         throws SocketException,
                ClientReceiveException,
                ClientSendException,
                IOException

Sends the DM / COA packet.

Sends the packet to the client. It will perform this several times as defined by 'retries' plus 1 if the response times out.

Returns:

The type of packet received.

Throws:

SocketException - if there's a socket problem.

ClientSendException - if there's a problem sending the packet (highly unlikely).

ClientSendException - if the 'try' count has been reached or the received packet type is unexpected.

IOException - if the debug file cannot be opened.

ClientReceiveException

setDebug

public void setDebug(boolean debug)

Set debugging on or off. Debugging information is written to the standard output. The information includes the packet contents, attributes, and the reason for the Access_BadPacket result from the authenticate() and accounting() methods. The reason is in the title of the packet display. If the output is sent to a file the file is overwritten each time the class is instantiated.

Parameters:

debug - Use true to enable debugging, false to disable debugging. The standard output is used.

See Also:

RADIUSClient.Access_BadPacket

setDebug

public void setDebug(boolean debug,
                     String fileName)
              throws IOException

Set debugging on or off. Debugging information is written to a file or the standard output. The information includes the packet contents, attributes, and the reason for the Access_BadPacket result from the authenticate() and accounting() methods. The reason is in the title of the packet display.

Parameters:

debug - Use true to enable debugging, false to disable debugging.

fileName - Debugging information will be written to this file. If the file name is null the standard output is used.

Throws:

IOException - if there's a problem opening the debugging output.

See Also:

RADIUSClient.Access_BadPacket, logToDebug()

setPort

public void setPort(int port)

Set the DMCOA port number if the standard port number isn't used.

Parameters:

port - Port number.

setRequestAttributes

public void setRequestAttributes(AttributeList requestList)

Set the request attributes. These attributes should contain the following attributes from the original packet with the original values:
NAS Identfiers:

• NAS-IP-Address
• NAS-Identifier
• NAS-IPv6-Address

Session Identifiers

• User-Name
• NAS-Port
• Framed-IP-Address
• Called-Station-Id
• Calling-Station-Id
• Acct-Session-Id
• Acct-Multi-Session-Id
• NAS-Port-Type
• NAS-Port-Id
• Originating-Line-Info
• Framed-Interface-Id
• Framed-IPv6-Prefix

Additional attributes peculiar to CoA and Disconnect requests are also added.

setRetries

public void setRetries(int retries)

Set the number of retries before giving up - default is RETRIES - you must specify at least one retry or no packets will be sent.

Parameters:

retries - Number of times to perform the request before giving up.

setTimeout

public void setTimeout(int timeout)

Set the timeout - default is TIMEOUT.

Parameters:

timeout - Number of milliseconds until the client times out.