com.theorem.radius3
Class RADIUSClient

Object
  RADIUSClient

All Implemented Interfaces:

Serializable

public final class RADIUSClient

extends Object

implements Serializable

RADIUS Client for applications. This provides a platform independent way to authenticate and perform accounting for an entity. The RADIUS client is in compliance with RFC 2138 & 2139.

Each different authentication, accounting, or extended packet MUST use a new constructor OR call the reset method (reset()). If a back up server is contacted the same constructor may be used. Retries because of timeouts MUST use the same constructor and NOT use the reset() method between retries. This is required to maintain the same packet Identifier and socket for retries. A different packet identifier is required for a new request. A different socket may be required if more than 256 outstanding radius requests are created.

Provides full Access-Request/Access-Accept and Access-Challenge authentication. Accounting-Request is also fully supported.

See Also:

Serialized Form

Field Summary

static int	Access_Accept Access_Accept is returned if an authentication succeeded, value = 2.
static int	Access_BadPacket Access_BadPacket is returned for a number of reasons, value = 0.
static int	Access_Challenge Access_Challenge is returned if an authentication is challenged, value = 11.
static int	Access_Reject Access_Reject is returned if an authentication failed, value = 3.
static int	Access_Request Access_Request is the packet type for authentication, value = 1.
static int	Accounting_Request Accounting_Request packet type, value = 4.
static int	Accounting_Response Accounting_Response packet type, value = 5.
static int	ACCT_PORT Port number (1813) for RADIUS Accounting
static int	ALT_ACCT_PORT Original RADIUS Accounting port number (1646) still in use on non-standard servers.
static int	ALT_AUTH_PORT Original RADIUS Authentication port number (1645) still in use on non-standard servers.
static int	AUTH_PORT Port number (1812) for RADIUS Authentication
static int	CoA_ACK Acknowledgement of a Change-of-Authorization request, value = 44.
static int	CoA_NAK Refusal of a Change-of-Authorization request, value = 45.
static int	CoA_Request Change-of-Authorization request packet, value = 43.
static int	Disconnect_ACK Client response to a Disconnect-Request acknowledging the disconnect message, value = 41.
static int	Disconnect_NAK Client response to a Disconnect-Request refusing the disconnect message request, value = 42.
static int	Disconnect_Request Disconnect-Request - request that a client disconnect message, value = 40.
static int	DMCOA_PORT The Disconnect-Request port UDP port 3799.
static int	ERROR_AUTHENTICATOR Access_BadPacket Reason: Bad authenticator = 5.
static int	ERROR_CORRUPT Access_BadPacket Reason: Attribute data is corrupt = 4.
static int	ERROR_DES Access_BadPacket Reason: DES encoding has a problem - key length, unable to locate the DES algorithm, etc. = 9.
static int	ERROR_DUPLICATE Access_BadPacket Reason: Duplicate packet received = 1.
static int	ERROR_MESSAGE_AUTHENTICATOR Access_BadPacket Reason: Bad Message-Authenticator attribute = 6.
static int	ERROR_MISMATCHED_ID Access_BadPacket Reason: Packet identifier sent doesn't match the received identifier = 3.
static int	ERROR_MISSING_USER_NAME Access_BadPacket Reason: Packet being sent has a User-Name of null = 2.
static int	ERROR_NONE Access_BadPacket Reason: No error = 0.
static int	ERROR_PACKET_SIZE Access_BadPacket Reason: The packet size is incorrect - too small or physical size is smaller than stated size = 8.
static int	ERROR_WRONG_HOST Access_BadPacket Reason: The reply packet did not arrive from the correct host.
static int	MAX_PACKET_SIZE Maximum packet size (4096) as specified in the RFC.
ClientModule	module Access to the module methods.
static int	SOCKET_TIMEOUT Default RADIUS timeout, value = 10000 ms.
static String	Version Client software version number ("3.45h")

Constructor Summary

RADIUSClient(InetAddress rHost, int port, byte[] secret, int timeout)
Class constructor creates the RADIUS Client.

RADIUSClient(InetAddress rHost, int port, String secret)
Class constructor creates the RADIUS Client.

RADIUSClient(InetAddress rHost, int port, String secret, int timeout)
Class constructor creates the RADIUS Client.

RADIUSClient(String rHost, int port, String secret)
Class constructor creates the RADIUS Client.

RADIUSClient(String rHost, int port, String secret, int timeout)
Class constructor creates the RADIUS Client.

Method Summary

int	accounting(AttributeList alist) Send Accounting information.
int	accounting(int packetType, AttributeList alist) Send Accounting information.
int	accountingRetry() Retry sending an accounting packet which automatically includes the Acct-Delay-Time attribute.
void	addDictionary(RADIUSDictionary dict) Add a dictionary to the RADIUS client's knowledge of vendor Id's and attribute names / types.
void	allowEmptyAttributes(boolean enable) Deprecated. - This method does nothing. RFC 2865 allows empty attribute values.
int	authenticate(AttributeList alist) Actually perform the authentication.
int	authenticate(byte[] packetData) Send authentication information using raw packet data.
int	authenticate(byte[] password, AttributeList alist) Send CHAP Authentication information.
int	authenticate(int packetType, AttributeList alist) Send an authentication request with a particular packet type.
int	authenticate(String password, AttributeList alist) Send CHAP Authentication information.
int	authenticate(String name, String password, AttributeList alist) Send PAP Authentication information.
void	bind(InetAddress localAddr) Bind the radius client to a particular local address.
void	bind(InetAddress localAddr, int bindPort) Bind the radius client to a particular local address and port.
void	bind(String localAddr) Bind the radius client to a particular local address.
static boolean	checkAccountingAuthenticator(byte[] radiusRecvBuf, int radiusRecvBufLen, byte[] radiusAuthenticator, byte[] radiusSecretBytes) Check the accounting authenticator - not to be used by a normal client - this is checked automatically internally.
static boolean	checkAuthenticator(byte[] radiusRecvBuf, int radiusRecvBufLen, byte[] radiusAuthenticator, byte[] radiusSecretBytes) Check an authentication authenticator on a packet and is not expected to be called by programmers.
void	close() End the authentication session
boolean	cmpMSCHAP2(byte[] name, byte[] password, AttributeList list) Compare an MS-CHAP V2 response to the request to determine if the authentication worked and we aren't being fooled by a rogue RADIUS Server.
byte[]	createChallenge16() Create random 16 byte challenge.
byte[]	createChallenge8() Create random 8 byte challenge.
void	createCHAP(byte[] password, AttributeList list) Create a CHAP password from a plain text password.
void	createMSCHAP(byte[] password, AttributeList list) Create an MS-CHAP password from a non-plain text (or plain text) password.
void	createMSCHAP2(byte[] name, byte[] password, AttributeList list) Create an MS-CHAP V2 password from a non-plain text (or plain text) password.
byte[]	decode(byte[] pwdBytes) Decode a PAP password.
int	dmcoa(int packetType, AttributeList alist) Send a Disconnect-Request or CoA-Request packet to be used when simulating a server sending a DM/COA message.
byte[]	encryptPassword(byte[] pwdBytes) Encrypt the password.
int	extended(int packetType, AttributeList alist) Deprecated. See authenticate() and accounting(). This method only accesses the authentication server.
AttributeList	getAttributes() Return attribute list from an authentication or accounting response.
static byte[]	getBytes(String str) Encode a string using UTF8 encoding.
boolean	getDebugIndicator() Get the debugging indicator value.
int	getError() Get the error value when an Access-BadPacket is returned from the authenticate() or accounting() methods
String	getErrorString() Get the name of the Access_BadPacket error.
int	getMaximumPacketSize() Get the maximum packet size.
Object	getModuleInstance(String moduleName, Object obj) Instantiate a client support module.
MPPE	getMSCHAPMPPE(boolean encrypted) Get the MS-CHAP V1 / V2 MPPE key information from the response packet.
int	getPacketType() Get the packet type returned by an authentication or accounting request.
String	getPacketTypeName() Get the name of the packet type returned by an authentication or accounting request.
String	getPacketTypeName(int packetType) Get the name of the packet type returned by an authentication or accounting request.
byte[]	getPassword() Get the User-Password/Chap-Password as a binary value.
AttributeList	getRequestAttributes() Explicitly get the original request attribute list.
byte[]	getRequestAuthenticator() Get the Access-Request Authenticator.
byte[]	getSecret() Get the NAS secret.
InetAddress	getServer() Get the RADIUS server address.
byte[]	getTunnelPassword(int tag) Decode a Tunnel-Password.
void	logToDebug(String msg) Log a message to the debug file or stdout if debugging hasn't been set up.
void	reset() Reset the client for a new request.
int	retry() Retry sending a packet.
int	sendRawPacket(byte[] packetData) Send RADIUS packet information using raw packet data.
boolean	setDebug(boolean debug) Set debugging on or off.
void	setDebug(boolean debug, String fileName) Set debugging on or off.
boolean	setEncoding(String enc) Deprecated. RADIUS standards require UTF8 coding. Always returns true.
void	setMaximumPacketSize(int maxPacketSize) Set the maximum packet size.
void	setMessageAuthenticator(boolean enabled) Disable/enable the creation of a Message-Authenticator in authentication packets; the default is to enable it for security.
static boolean	testEnc(String enc) Test a character encoding scheme.
String	toString() Return representation of the RADIUS connection.
byte[]	trim(byte[] pwdBytes) Trim trailing nulls from a decrypted password.

Methods inherited from class Object

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

Field Detail

Version

public static final String Version

Client software version number ("3.45h")

See Also:

Constant Field Values

AUTH_PORT

public static final int AUTH_PORT

Port number (1812) for RADIUS Authentication

See Also:

authenticate(), Constant Field Values

ALT_AUTH_PORT

public static final int ALT_AUTH_PORT

Original RADIUS Authentication port number (1645) still in use on non-standard servers.

See Also:

authenticate(), Constant Field Values

ACCT_PORT

public static final int ACCT_PORT

Port number (1813) for RADIUS Accounting

See Also:

accounting(), Constant Field Values

ALT_ACCT_PORT

public static final int ALT_ACCT_PORT

Original RADIUS Accounting port number (1646) still in use on non-standard servers.

See Also:

accounting(), Constant Field Values

DMCOA_PORT

public static final int DMCOA_PORT

The Disconnect-Request port UDP port 3799.

See Also:

Constant Field Values

Access_Request

public static final int Access_Request

Access_Request is the packet type for authentication, value = 1.

See Also:

Constant Field Values

Access_Accept

public static final int Access_Accept

Access_Accept is returned if an authentication succeeded, value = 2.

See Also:

authenticate(), Constant Field Values

Access_Reject

public static final int Access_Reject

Access_Reject is returned if an authentication failed, value = 3.

See Also:

authenticate(), Constant Field Values

Access_Challenge

public static final int Access_Challenge

Access_Challenge is returned if an authentication is challenged, value = 11.

See Also:

authenticate(), accounting(), Constant Field Values

Disconnect_Request

public static final int Disconnect_Request

Disconnect-Request - request that a client disconnect message, value = 40.

See Also:

authenticate(int packetType, AttributeList alist), Constant Field Values

Disconnect_ACK

public static final int Disconnect_ACK

Client response to a Disconnect-Request acknowledging the disconnect message, value = 41.

See Also:

authenticate(int packetType, AttributeList alist), Constant Field Values

Disconnect_NAK

public static final int Disconnect_NAK

Client response to a Disconnect-Request refusing the disconnect message request, value = 42.

See Also:

authenticate(int packetType, AttributeList alist), Constant Field Values

CoA_Request

public static final int CoA_Request

Change-of-Authorization request packet, value = 43.

See Also:

authenticate(int packetType, AttributeList alist), Constant Field Values

CoA_ACK

public static final int CoA_ACK

Acknowledgement of a Change-of-Authorization request, value = 44.

See Also:

authenticate(int packetType, AttributeList alist), Constant Field Values

CoA_NAK

public static final int CoA_NAK

Refusal of a Change-of-Authorization request, value = 45.

See Also:

authenticate(int packetType, AttributeList alist), Constant Field Values

Access_BadPacket

public static final int Access_BadPacket

Access_BadPacket is returned for a number of reasons, value = 0. This is slightly misnamed as any response from any packet may return this value (accounting, DM/COA, extended packet types).

Reasons:

• The returned authenticator is incorrect. This can mean that the shared secret used by the client doesn't match the servers secret.
• The packet identifier of the received packet isn't the same as the request identifier.
• The User-Name is missing or null when using any of the authentication() methods.
• The reply packet's attributes are corrupt.
• The Message-Authenticator attribute, if present, is incorrect.
  The exact nature of the problem can be found using the getError() and getErrorString() methods.

  See Also:

  Constant Field Values

Accounting_Request

public static final int Accounting_Request

Accounting_Request packet type, value = 4.

See Also:

Constant Field Values

Accounting_Response

public static final int Accounting_Response

Accounting_Response packet type, value = 5.

See Also:

accounting(), Constant Field Values

MAX_PACKET_SIZE

public static final int MAX_PACKET_SIZE

Maximum packet size (4096) as specified in the RFC. This can be increased using setMaximumPacketSize(). The server receiving the packet must be able to handle a larger size.

See Also:

Constant Field Values

SOCKET_TIMEOUT

public static final int SOCKET_TIMEOUT

Default RADIUS timeout, value = 10000 ms.

See Also:

Constant Field Values

ERROR_NONE

public static final int ERROR_NONE

Access_BadPacket Reason: No error = 0.

See Also:

Constant Field Values

ERROR_DUPLICATE

public static final int ERROR_DUPLICATE

Access_BadPacket Reason: Duplicate packet received = 1.

See Also:

Constant Field Values

ERROR_MISSING_USER_NAME

public static final int ERROR_MISSING_USER_NAME

Access_BadPacket Reason: Packet being sent has a User-Name of null = 2.

See Also:

Constant Field Values

ERROR_MISMATCHED_ID

public static final int ERROR_MISMATCHED_ID

Access_BadPacket Reason: Packet identifier sent doesn't match the received identifier = 3.

See Also:

Constant Field Values

ERROR_CORRUPT

public static final int ERROR_CORRUPT

Access_BadPacket Reason: Attribute data is corrupt = 4.

See Also:

Constant Field Values

ERROR_AUTHENTICATOR

public static final int ERROR_AUTHENTICATOR

Access_BadPacket Reason: Bad authenticator = 5.

See Also:

Constant Field Values

ERROR_MESSAGE_AUTHENTICATOR

public static final int ERROR_MESSAGE_AUTHENTICATOR

Access_BadPacket Reason: Bad Message-Authenticator attribute = 6.

See Also:

Constant Field Values

ERROR_WRONG_HOST

public static final int ERROR_WRONG_HOST

Access_BadPacket Reason: The reply packet did not arrive from the correct host. The IP address for the reply is not the same as the the destination host. = 7.

See Also:

Constant Field Values

ERROR_PACKET_SIZE

public static final int ERROR_PACKET_SIZE

Access_BadPacket Reason: The packet size is incorrect - too small or physical size is smaller than stated size = 8.

See Also:

Constant Field Values

ERROR_DES

public static final int ERROR_DES

Access_BadPacket Reason: DES encoding has a problem - key length, unable to locate the DES algorithm, etc. = 9.

See Also:

Constant Field Values

module

public transient ClientModule module

Access to the module methods. E.g module.eapttls refers to the EAPTLS package.

Constructor Detail

RADIUSClient

public RADIUSClient(String rHost,
                    int port,
                    String secret)
             throws SocketException,
                    UnknownHostException

Class constructor creates the RADIUS Client. Attempts to make a connection to the given RADIUS client. Each new authentication request requires a new constructor.

Parameters:

rHost - The RADIUS host name or address.

port - Port number for the RADIUS host.

secret - The shared secret between this client and the RADIUS server.

Throws:

SocketException - Socket creation problems.

UnknownHostException - Can't find the RADIUS host.

RADIUSClient

public RADIUSClient(InetAddress rHost,
                    int port,
                    String secret)
             throws SocketException

Class constructor creates the RADIUS Client. Attempts to make a connection to the given RADIUS client. Each new authentication request requires a new constructor.

Parameters:

rHost - The RADIUS host address.

port - Port number for the RADIUS host.

secret - The shared secret between this client and the RADIUS server.

Throws:

SocketException - Socket creation problems.

RADIUSClient

public RADIUSClient(String rHost,
                    int port,
                    String secret,
                    int timeout)
             throws SocketException,
                    UnknownHostException

Class constructor creates the RADIUS Client. Attempts to make a connection to the given RADIUS client.

Parameters:

rHost - The RADIUS host name or address.

port - Port number for the RADIUS host.

secret - The shared secret between this client and the RADIUS server.

timeout - Socket timeout in milliseconds.

Throws:

SocketException - Socket creation problems.

UnknownHostException

RADIUSClient

public RADIUSClient(InetAddress rHost,
                    int port,
                    String secret,
                    int timeout)
             throws SocketException

Class constructor creates the RADIUS Client. Attempts to make a connection to the given RADIUS client.

Parameters:

rHost - The RADIUS host name or address.

port - Port number for the RADIUS host.

secret - The shared secret between this client and the RADIUS server.

timeout - Socket timeout in milliseconds.

Throws:

SocketException - Socket creation problems.

RADIUSClient

public RADIUSClient(InetAddress rHost,
                    int port,
                    byte[] secret,
                    int timeout)
             throws SocketException

Class constructor creates the RADIUS Client. Attempts to make a connection to the given RADIUS client.

Parameters:

rHost - The RADIUS host name or address.

port - Port number for the RADIUS host.

secret - The shared secret between this client and the RADIUS server.

timeout - Socket timeout in milliseconds.

Throws:

SocketException - Socket creation problems.

Method Detail

reset

public void reset()
           throws SocketException

Reset the client for a new request.
NOTE: This should ONLY be used for a new request and NOT for a retry of the same request.

Throws:

SocketException - if there's a problem creating the datagram socket or if the client is bound to an address and there are no free ports.

bind

public void bind(String localAddr)
          throws SocketException,
                 UnknownHostException

Bind the radius client to a particular local address.

Parameters:

localAddr - Local address.

Throws:

SocketException - if the socket can't be bound to the local address.

UnknownHostException - if the local address is unknown.

bind

public void bind(InetAddress localAddr)
          throws SocketException

Bind the radius client to a particular local address.

Parameters:

localAddr - Local address.

Throws:

SocketException - if the socket can't be bound to the local address.

bind

public void bind(InetAddress localAddr,
                 int bindPort)
          throws SocketException

Bind the radius client to a particular local address and port.

Parameters:

localAddr - Local address.

bindPort - local port.

Throws:

SocketException - if the socket can't be bound to the local address.

setMessageAuthenticator

public void setMessageAuthenticator(boolean enabled)

Disable/enable the creation of a Message-Authenticator in authentication packets; the default is to enable it for security.

If the attribute list contains a Message-Authenticator attribute it will be retained regardless of this setting. Protocols like EAP require this attribute to function.

Parameters:

enabled - Set to true to enable the Message-Authenticator (default) or false to disable it. Disabling it results in poorer security.

Since:

3.45d

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:

Access_BadPacket, logToDebug()

setDebug

public boolean 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.

Returns:

False if the standard output can't be opened.

See Also:

Access_BadPacket

getDebugIndicator

public boolean getDebugIndicator()

Get the debugging indicator value.

Returns:

True if debugging is enabled, false otherwise.

Since:

3.26

logToDebug

public void logToDebug(String msg)

Log a message to the debug file or stdout if debugging hasn't been set up. This is used to log message to the same place the RADIUSClient logs.

Parameters:

msg - Message to write.

See Also:

setDebug()

authenticate

public int authenticate(String password,
                        AttributeList alist)
                 throws ClientSendException,
                        ClientReceiveException

Send CHAP Authentication information.

Note: the authenticate method only tries once to contact the RADIUS host. Either the UDP authentication or reply packet may be lost, or the server may have chosen not to answer. Catching a ClientSendException or ClientReceiveException lets you know which one of the UDP packets was lost. Catching an IOException will catch both exceptions. The calling program must supply the retry algorithm or contact a backup RADIUS server.

The class RADIUSEncrypt may be useful to encode a returning password for comparison to the original in an Access-Challenge response.

The User-Name attribute is expected to be set.

Parameters:

password - Password which may be null or empty. If the password is null no User-Password attribute will be generated.

Returns:

response packet type.

Throws:

ClientSendException - If a problem occurs sending a packet.

ClientReceiveException - If a problem occurs receiving a packet.

See Also:

Access_Accept, Access_Reject, Access_Challenge, Access_BadPacket, getError()

authenticate

public int authenticate(String name,
                        String password,
                        AttributeList alist)
                 throws ClientSendException,
                        ClientReceiveException

Send PAP Authentication information.

Note: the authenticate method only tries once to contact the RADIUS host. Either the UDP authentication or reply packet may be lost, or the server may have chosen not to answer. Catching a ClientSendException or ClientReceiveException lets you know which one of the UDP packets was lost. Catching an IOException will catch both exceptions. The calling program must supply the retry algorithm or contact a backup RADIUS server.

The class RADIUSEncrypt may be useful to encode a returning password for comparison to the original in an Access-Challenge response.

Parameters:

name - Entity name to authenticate.

password - Password for the entity name. If the password is null no User-Password attribute will be generated.

alist - AttributeList List of additional attributes.

Returns:

* @return response packet type.

Throws:

ClientSendException - If a problem occurs sending a packet.

ClientReceiveException - If a problem occurs receiving a packet.

See Also:

Access_Accept, Access_Reject, Access_Challenge, Access_BadPacket, getError()

authenticate

public int authenticate(byte[] password,
                        AttributeList alist)
                 throws ClientSendException,
                        ClientReceiveException

Send CHAP Authentication information.

Note: the authenticate method only tries once to contact the RADIUS host. Either the UDP authentication or reply packet may be lost, or the server may have chosen not to answer. Catching a ClientSendException or ClientReceiveException lets you know which one of the UDP packets was lost. Catching an IOException will catch both exceptions. The calling program must supply the retry algorithm or contact a backup RADIUS server.

The User-Name attribute is expected to be set.

Parameters:

password - Plain text password.

alist - List of request attributes.

Returns:

response packet type.

Throws:

ClientSendException - If a problem occurs sending a packet.

ClientReceiveException - If a problem occurs receiving a packet.

See Also:

Access_Accept, Access_Reject, Access_Challenge, Access_BadPacket, getError()

authenticate

public int authenticate(AttributeList alist)
                 throws ClientSendException,
                        ClientReceiveException

Actually perform the authentication.

Parameters:

alist - List of Attributes.

Returns:

response packet type.

Throws:

ClientSendException - If a problem occurs sending a packet.

ClientReceiveException - If a problem occurs receiving a packet.

See Also:

getError()

authenticate

public int authenticate(int packetType,
                        AttributeList alist)
                 throws ClientSendException,
                        ClientReceiveException

Send an authentication request with a particular packet type.

Parameters:

packetType - The packet type to send. This would generally be an extended packet type.

alist - List of Attributes.

Returns:

response packet type.

Throws:

ClientSendException - If a problem occurs sending a packet.

ClientReceiveException - If a problem occurs receiving a packet.

See Also:

getError()

authenticate

public int authenticate(byte[] packetData)
                 throws ClientSendException,
                        ClientReceiveException

Send authentication information using raw packet data.

Note: the authenticate method only tries once to contact the RADIUS host. Either the UDP authentication or reply packet may be lost, or the server may have chosen not to answer. Catching a ClientSendException or ClientReceiveException lets you know which one of the UDP packets was lost. Catching an IOException will catch both exceptions. The calling program must supply the retry algorithm or contact a backup RADIUS server.

Parameters:

packetData - Raw data to be sent as a packet.

Returns:

response packet type.

Throws:

ClientSendException - If a problem occurs sending a packet.

ClientReceiveException - If a problem occurs receiving a packet.

See Also:

Access_Accept, Access_Reject, Access_Challenge, Access_BadPacket, getError()

sendRawPacket

public int sendRawPacket(byte[] packetData)
                  throws ClientSendException,
                         ClientReceiveException

Send RADIUS packet information using raw packet data.

Note: the method only tries once to contact the RADIUS host. Either the UDP authentication or reply packet may be lost, or the server may have chosen not to answer. Catching a ClientSendException or ClientReceiveException lets you know which one of the UDP packets was lost. Catching an IOException will catch both exceptions. The calling program must supply the retry algorithm or contact a backup RADIUS server.

Parameters:

packetData - Raw data to be sent as a packet.

Returns:

response packet type.

Throws:

ClientSendException - If a problem occurs sending a packet.

ClientReceiveException - If a problem occurs receiving a packet.

Since:

3.20

See Also:

Access_Accept, Access_Reject, Access_Challenge, Access_BadPacket, getError()

accounting

public int accounting(AttributeList alist)
               throws ClientSendException,
                      ClientReceiveException

Send Accounting information.

Note: the accounting method only tries once to contact the RADIUS host. The UDP authentication packet may be lost or the response may be lost. Catching a ClientSendException or ClientReceiveException lets you know which one of the UDP packets was lost. Catching an IOException will catch both exceptions. The calling program must supply the retry algorithm or contact a backup RADIUS server.

Any returned accounting attributes can be acquired by using the getAttributes method.

Parameters:

alist - List of attributes to send.

Returns:

response packet type. An Access_BadPacket means there was a problem authenticating the returned packet, or the password passed to authenticate() is null.

Throws:

ClientSendException - If a problem occurs sending a packet.

ClientReceiveException - If a problem occurs receiving a packet.

See Also:

getAttributes(), Accounting_Response, Access_BadPacket, getError()

accounting

public int accounting(int packetType,
                      AttributeList alist)
               throws ClientSendException,
                      ClientReceiveException

Send Accounting information.

Note: the accounting method only tries once to contact the RADIUS host. The UDP authentication packet may be lost or the response may be lost. Catching a ClientSendException or ClientReceiveException lets you know which one of the UDP packets was lost. Catching an IOException will catch both exceptions. The calling program must supply the retry algorithm or contact a backup RADIUS server.

Any returned accounting attributes can be acquired by using the getAttributes method.

Parameters:

packetType - The packet type to send. This would generally be an extended packet type.

alist - List of attributes to send.

Returns:

response packet type. An Access_BadPacket means there was a problem authenticating the returned packet, or the password passed to authenticate() is null.

Throws:

ClientSendException - If a problem occurs sending a packet.

ClientReceiveException - If a problem occurs receiving a packet.

See Also:

getAttributes(), Accounting_Response, Access_BadPacket, getError()

dmcoa

public int dmcoa(int packetType,
                 AttributeList alist)
          throws ClientSendException,
                 ClientReceiveException

Send a Disconnect-Request or CoA-Request packet to be used when simulating a server sending a DM/COA message.

After the creation of the RADIUSClient the method bind(InetAddress bindAddr, int bindPort) must be called to bind the client to the DM/COA port. This binds the DM/COA port and address so that the client's response will return to the waiting port. The DM/COA protocol requires both the client and server to use the same port (3799).

Any returned accounting attributes can be acquired by using the getAttributes method.

Parameters:

packetType - The packet type to send.

alist - List of attributes to send.

Returns:

response packet type. An Access_BadPacket means there was a problem authenticating the returned packet, or the password passed to authenticate() is null.

Throws:

ClientSendException - If a problem occurs sending a packet.

ClientReceiveException - If a problem occurs receiving a packet.

See Also:

getAttributes(), Accounting_Response, Access_BadPacket, getError()

extended

public int extended(int packetType,
                    AttributeList alist)
             throws ClientSendException,
                    ClientReceiveException

Deprecated. See authenticate() and accounting(). This method only accesses the authentication server.

Send an extended packet type to an authentication server.

Sends an packet of a specific type to the authentication server. Normally an Access-Request or an Accounting-Request type packet is sent. This allows other types of packets to be sent, such as a Resource-Free-Request.

Note: the extended method only tries once to contact the RADIUS host. The UDP extended packet may be lost or the response may be lost. Catching a ClientSendException or ClientReceiveException lets you know which one of the UDP packets was lost. Catching an IOException will catch both exceptions. The calling program must supply the retry algorithm or contact a backup RADIUS server.

Any returned extended packet type attributes can be acquired by using the getAttributes method.

Parameters:

packetType - Type of packet to send.

alist - List of attributes to send.

Returns:

response packet type. An PacketType.Access_BadPacket means there was a problem authenticating the packet (bad authenticator).

Throws:

ClientSendException - If a problem occurs sending a packet.

ClientReceiveException - If a problem occurs receiving a packet.

See Also:

getAttributes(), PacketType, getError()

accountingRetry

public final int accountingRetry()
                          throws ClientSendException,
                                 ClientReceiveException

Retry sending an accounting packet which automatically includes the Acct-Delay-Time attribute. This works with all Acct-Status-Type values. A reset() is still required before this method is called.

This is used if an accounting packet experiences a timeout waiting for a reply. A ClientReceiveException is thrown when a timeout occurs.

The accounting packet retry is special in that an Acct-Delay-Time attribute is added or updated from the time the original accounting packet was sent. This method performs one retry and does not provide delays.

This will fail with a ClientSendException if A) no accounting packet has been sent; B) another type of packet has been sent between the original accounting Start or Stop packet and the accountingRetry(); C) there is no network. The Acct-Delay-Time will be incorrect if other types of accounting packets like Interim-Updates are sent in the meantime through the same RADIUSClient.

Returns:

response packet type.

Throws:

ClientSendException - will be thrown if the original packet has not been sent (nothing to retry). In other words a retry without an original accounting packet will fail.

ClientReceiveException - if there's a problem receiving the data.

Since:

3.45d

retry

public int retry()
          throws ClientSendException,
                 ClientReceiveException

Retry sending a packet.

This is used if a packet experienced a timeout receiving a packet. A ClientReceiveException is thrown when a timeout occurs. Other errors may cause the ClientReceiveException but in all cases a retry is in order. The original request attributes are resent with the original packet identifier and authenticator.

This method performs one retry and does not provide delays.

Returns:

The response packet type.

Throws:

ClientSendException - will be thrown if the original packet has not been sent (nothing to retry). In other words a retry without an original try will fail.

ClientReceiveException - if there's a problem receiving the data.

setMaximumPacketSize

public void setMaximumPacketSize(int maxPacketSize)

Set the maximum packet size. By default the maximum size is 4 K. Be sure that the RADIUS Server is capable of receiving larger packet sizes before the value is changed.

Parameters:

maxPacketSize - New packet size.

getMaximumPacketSize

public int getMaximumPacketSize()

Get the maximum packet size.

Returns:

The maximum packet size.

Since:

3.23

getAttributes

public AttributeList getAttributes()

Return attribute list from an authentication or accounting response. If the radius client thows a ClientReceiveException or a ClientSendException the returned attributes will be the original request's attributes.

If a Access_BadPacket result was returned the attributes may be from the response or the request depending on the error.

Returns:

the AttributeList with return attributes. If no attributes are available the list will be empty. Note that Accounting-Response packets are often empty.

getRequestAttributes

public AttributeList getRequestAttributes()

Explicitly get the original request attribute list. This will retrieve the attributes from the last request.

Returns:

The request attributes.

close

public void close()

End the authentication session

getPassword

public byte[] getPassword()

Get the User-Password/Chap-Password as a binary value. If the User-Password is absent the authenticator is returned as required by CHAP authentication.

Returns:

binary value of User-Password or the authenticator.

setEncoding

public boolean setEncoding(String enc)

Deprecated. RADIUS standards require UTF8 coding. Always returns true.

Set character encoding. The default is "UTF-8". This is used to convert strings to bytes for the password and name.

Parameters:

enc - Character encoding (e.g. Cp277)

Returns:

true if the encoding is acceptable. Otherwise the platform's default encoding will be used.

createCHAP

public void createCHAP(byte[] password,
                       AttributeList list)

Create a CHAP password from a plain text password.

Parameters:

password - Plain text password to encode. It should be encoded from a string as UTF8.

list - Attribute Add the CHAP attributes to this list.

createMSCHAP

public void createMSCHAP(byte[] password,
                         AttributeList list)
                  throws RADIUSException

Create an MS-CHAP password from a non-plain text (or plain text) password. This method adds one Microsoft Vendor-Specific attribute to the attribute list.

Some servers like their MS VSA's separate so we will observe this anomally. Each MS-CHAP VSA will hold one sub-attribute.

Parameters:

password - Plain text password to encode. It must not be in encoded in UNICODE format. The default UTF8 encodings is sufficient.

list - Attribute Add the CHAP attributes to this list.

Throws:

RADIUSException - if there's a problem running DES encoding. See getError() or the RADIUSException for the reason.

getMSCHAPMPPE

public MPPE getMSCHAPMPPE(boolean encrypted)

Get the MS-CHAP V1 / V2 MPPE key information from the response packet. MPPE keys are part of the Microsoft Point-to-Point Encryption Protocol (MPPE).

Parameters:

encrypted - True if the keys are expected to be encrypted, false if they're in plain text. Unless debugging the keys must always be encrypted.

Returns:

the MSCHAPMPPE object. with the keys and maybe policy information.

createMSCHAP2

public void createMSCHAP2(byte[] name,
                          byte[] password,
                          AttributeList list)
                   throws RADIUSException

Create an MS-CHAP V2 password from a non-plain text (or plain text) password. This method adds one Microsoft Vendor-Specific attribute to the attribute list. MS-CHAP V2 requires mutual authentication of the client by the server and then the client authenticates the server's response. A complete check must use cmpMSCHAP2() to authenticate the server's response before the authentication is finally accepted. A result of Access-Accept is not sufficient.

Parameters:

name - User-Name attribute value, generally stripped of realm information. It must not be in encoded in UNICODE format. The default UTF8 encoding is sufficient as it will be translated to UNICODE when necessary.

password - Plain text password to encode. It should be encoded from a string as UTF8.

list - Attribute Add the CHAP attributes to this list.

Throws:

RADIUSException - if there's a problem running DES encoding. See getError() or the RADIUSException for the reason.

cmpMSCHAP2

public boolean cmpMSCHAP2(byte[] name,
                          byte[] password,
                          AttributeList list)
                   throws RADIUSException

Compare an MS-CHAP V2 response to the request to determine if the authentication worked and we aren't being fooled by a rogue RADIUS Server.

Parameters:

name - User-Name attribute value, generally stripped of realm information. It must not be in encoded in UNICODE format. The default UTF8 encoding is sufficient.

password - Plain text password to encode. It should be encoded from a string as UTF8.

list - Attribute list containing the response.

Returns:

true if the MS-CHAP2-Success value is correct, false if there's a failure packet, the Ident field failed to match, or the Success value is incorrect.

Throws:

RADIUSException - if there's a problem running DES encoding. See getError() or the RADIUSException for the reason.

getTunnelPassword

public byte[] getTunnelPassword(int tag)

Decode a Tunnel-Password.

Parameters:

tag - Tunnel tag for this password.

Returns:

Tunnel password or null if there is no password or the password length does not match the length described in the encoded password. Trailing padding (0x00) bytes are stripped.

Since:

3.22

addDictionary

public void addDictionary(RADIUSDictionary dict)

Add a dictionary to the RADIUS client's knowledge of vendor Id's and attribute names / types. The server is aware of standard RADIUS attributes.

The dictionary aids the server in displaying attribute names and values.

Parameters:

dict - RADIUSDictionary.

toString

public String toString()

Return representation of the RADIUS connection.

Returns:

representation of the RADIUS connection.

checkAccountingAuthenticator

public static boolean checkAccountingAuthenticator(byte[] radiusRecvBuf,
                                                   int radiusRecvBufLen,
                                                   byte[] radiusAuthenticator,
                                                   byte[] radiusSecretBytes)

Check the accounting authenticator - not to be used by a normal client - this is checked automatically internally. This is for internal use only and use by very strange systems. The client performs this test internally. The Authenticator field in an Accounting-Response packet is called the Response Authenticator, and contains a one-way MD5 hash calculated over a stream of octets consisting of the Accounting- Response Code, Identifier, Length, the Request Authenticator field from the Accounting-Request packet being replied to, and the response attributes if any, followed by the shared secret. The resulting 16 octet MD5 hash value is stored in the Authenticator field of the Accounting-Response packet.

Parameters:

radiusRecvBuf - Buffer containing the entire radius packet.

radiusRecvBufLen - Length of actual data in the radiusRecvBuf.

radiusAuthenticator - Authenticator from the request packet.

radiusSecretBytes - Shared secret.

Returns:

True if the packet's authenticator is correct.

checkAuthenticator

public static boolean checkAuthenticator(byte[] radiusRecvBuf,
                                         int radiusRecvBufLen,
                                         byte[] radiusAuthenticator,
                                         byte[] radiusSecretBytes)

Check an authentication authenticator on a packet and is not expected to be called by programmers. This is for internal use only and use by very strange systems. The client performs this test internally.

Parameters:

radiusRecvBuf - packet data.

radiusRecvBufLen - packet data.length

radiusAuthenticator - Radius request authenticator.

radiusSecretBytes - Shared secret bytes.

encryptPassword

public byte[] encryptPassword(byte[] pwdBytes)

Encrypt the password.

 RFC 2138:
 The NAS and RADIUS server share a secret. That shared secret
 followed by the Request Authenticator is put through a one-way MD5
 hash to create a 16 octet digest value which is xored with the
 password entered by the user, and the xored result placed in the
 User-Password attribute in the Access-Request packet. See the
 entry for User-Password in the section on Attributes for a more
 detailed description.

 If the password is longer than 16 characters, a second one-way MD5
 hash is calculated over a stream of octets consisting of the
 shared secret followed by the result of the first xor. That hash
 is XORed with the second 16 octet segment of the password and
 placed in the second 16 octets of the String field of the User-
 Password Attribute.

 If necessary, this operation is repeated, with each xor result
 being used along with the shared secret to generate the next hash
 to xor the next segment of the password, to no more than 128
 characters.

 

Parameters:

pwdBytes - The password to encrypt. May be empty.

Returns:

encrypted password which will be padded with zero valued octets.

decode

public byte[] decode(byte[] pwdBytes)

Decode a PAP password.

Parameters:

pwdBytes - Password bytes to decode / encode.

Returns:

The resulting password or null if the password bytes are not a multiple of 16.

trim

public byte[] trim(byte[] pwdBytes)

Trim trailing nulls from a decrypted password. Decoded passwords may be padded with trailing nulls.

Parameters:

pwdBytes - Password bytes returned from decode().

Returns:

Trimmed password bytes.

getBytes

public static byte[] getBytes(String str)

Encode a string using UTF8 encoding. If UTF8 is not available the platform default is used.

Parameters:

str - String to encode.

Returns:

byte array of string encoded using UTF8.

testEnc

public static boolean testEnc(String enc)

Test a character encoding scheme.

Parameters:

enc - The character encoding name.

Returns:

false if the encoding name is unknown.

getRequestAuthenticator

public byte[] getRequestAuthenticator()

Get the Access-Request Authenticator. This is the authenticator sent with the request packet.

Returns:

Original authenticator

getPacketType

public int getPacketType()

Get the packet type returned by an authentication or accounting request. This has the same value as the accounting() and authentication() method return.

Returns:

packet type.

getPacketTypeName

public String getPacketTypeName()

Get the name of the packet type returned by an authentication or accounting request.

Returns:

packet type name.

Since:

3.23

getPacketTypeName

public String getPacketTypeName(int packetType)

Get the name of the packet type returned by an authentication or accounting request.

Parameters:

packetType - Packet type to look up.

Returns:

packet type name.

Since:

3.23

getSecret

public byte[] getSecret()

Get the NAS secret.

Returns:

secret.

getError

public int getError()

Get the error value when an Access-BadPacket is returned from the authenticate() or accounting() methods

Returns:

error value.

See Also:

ERROR_NONE, ERROR_DUPLICATE, ERROR_MISSING_USER_NAME, ERROR_MISMATCHED_ID, ERROR_CORRUPT, ERROR_AUTHENTICATOR, ERROR_MESSAGE_AUTHENTICATOR, ERROR_PACKET_SIZE

getErrorString

public String getErrorString()

Get the name of the Access_BadPacket error.

createChallenge16

public byte[] createChallenge16()

Create random 16 byte challenge.

Returns:

challenge.

createChallenge8

public byte[] createChallenge8()

Create random 8 byte challenge.

Returns:

challenge.

getServer

public InetAddress getServer()

Get the RADIUS server address.

Returns:

RADIUS server address.

Since:

3.28.2

getModuleInstance

public Object getModuleInstance(String moduleName,
                                Object obj)
                                   throws RADIUSModuleException

Instantiate a client support module. For example "EAPTLS" adds the EAP-TLS module.

Parameters:

moduleName - Name of module to instantiate. The module name may either be relative to the module package or a fully qualified class path. In some cases the class loader doesn't provide the necessary package information so even where the class is relative to the module packate it will be necessary to use a full path to the class.

obj - Object to pass to the module's constructor. If null the default contructor will be used.

Returns:

true if the module can be found otherwise false.

Throws:

RADIUSModuleException - if there's a problem registering the module.

Since:

3.26

allowEmptyAttributes

public void allowEmptyAttributes(boolean enable)

Deprecated. - This method does nothing. RFC 2865 allows empty attribute values.

Allow empty attributes.

Parameters:

enable - True allows empty attributes, False disallows them.