com.theorem.radserver3
Class AttributeList

Object
  AttributeList

All Implemented Interfaces:

Serializable

Direct Known Subclasses:

VendorSpecific

public class AttributeList

extends Object

implements Serializable

Provide a list of Attributes and provide the means to perform simple operations on the list.

See Also:

Serialized Form

Constructor Summary

AttributeList()
Construct an empty list.

AttributeList(Attribute[] list)
Construct a list from an array of attributes.

AttributeList(AttributeList list)
Construct a list from a list of attributes.

Method Summary

void	addAttribute(Attribute att) Add an attribute to the list.
void	addAttribute(int tag) Add an attribute with no value to the list.
void	addAttribute(int tag, byte[] data) Add an attribute to the list.
void	addAttribute(int tag, Date value) Add an attribute to the list.
void	addAttribute(int tag, InetAddress value) Add an attribute to the list.
void	addAttribute(int tag, int value) Add an attribute to the list.
void	addAttribute(int tag, int tunnelTag, byte[] data) Add a tunneling attribute to the list.
void	addAttribute(int tag, int tunnelTag, InetAddress data) Add a tunneling attribute to the list.
void	addAttribute(int tag, int tunnelTag, int data) Add a tunneling attribute to the list.
void	addAttribute(int tag, int tunnelTag, String data) Add a tunneling attribute to the list.
void	addAttribute(int tag, String value) Add an attribute to the list.
void	addAttribute(VendorSpecific vs) Add an attribute to the list.
void	clearAttributes() Clear all attributes.
void	createCHAPChallenge(byte[] plaintextPassword) Create an 16 byte CHAP-Challenge / CHAP-Password for a plain text password.
byte[]	createRadiusAttributeBlock() Create a RADIUS attribute block from the attribute list.
int	dataSize() Return the current data size of all attributes.
void	decodeAll(byte[] secret, byte[] authenticator) Decode all attributes in this AttributeList using a two byte SALT.
void	delete(int type) Delete an attribute.
void	deleteAll(int type) Delete all attributes of a given type..
Enumeration	elements() Provide an enumeration of attributes.
void	encodeAll(byte[] secret, byte[] authenticator) Encode all attributes in this AttributeList using a two byte SALT.
boolean	exists(int tag) Determine if an attribute type exists.
int	findPosition(int type) Find the starting position of an attribute in a RADIUS data block.
byte[][]	getAllBinaryAttributes(int type) Return all binary attributes of a particular attribute type.
String[]	getAllStringAttributes(int type) Return all matching String attributes of the given attribute type.
Attribute[]	getAttributeArray(int tag) Get an array of Attributes of a specific type.
Attribute	getAttributeAt(int n) Get the N'th attribute in the list.
AttributeList	getAttributeList(int type) Get a list of specific attributes.
Attribute[]	getAttributes() Get a list of attributes.
byte[]	getBinaryAttribute(int type) Return a binary attribute of a given type.
int	getInt(int type) Get an integer value (four octets) from an attribute.
InetAddress	getIPAttribute(int tag) Return an IP address from a 4 or 16 byte binary attribute (like NAS-IP-Address).
int	getShort(int type) Get a short value (two octets) from an attribute.
int	getSize() Return the size of the current list of attributes.
String	getStringAttribute(int type) Return a particular string attribute.
VendorSpecific[]	getVendorSpecific(int vendor) Get a list of Vendor-Specific attributes by Vendor Id.
Attribute[]	getVendorSpecific(int vendor, int vendorTag) Get a list of Vendor-Specific attributes by Vendor Id narrowed down to a particular tag.
boolean	loadRadiusAttributes(byte[] dataBlock, int offset, int len) Creates an attribute list from a raw attribute block.
boolean	loadRadiusAttributes(byte[] dataBlock, int offset, int len, boolean allowEmpty) Creates an attribute list from a raw attribute block perhaps allowing empty attributes.
void	mergeAttributes(Attribute[] a) Merge an attribute array with the current AttributeList.
void	mergeAttributes(AttributeList a) Merge another AttributeList with the current AttributeList.
AttributeList	mergeAttributes(AttributeList a, Attribute[] b) Merge two AttributeLists and return the resulting AttributeList.
AttributeList	mergeAttributes(AttributeList a, AttributeList b) Merge two attribute lists and return the resulting new AttributeList.
static InetAddress	parseIPAttribute(byte[] addr) Parse an IP address from a IPv4 (4 byte) binary attribute (like NAS-IP-Address).
static InetAddress	parseIPv6Attribute(byte[] addr) Parse an IP address from a 16 byte binary attribute (like NAS-IPv6-Address).
boolean	setAttribute(int type, byte[] data) Reset the value of an existing attribute.
void	setAttributeAt(int n, Attribute a) Set the N'th attribute in the list.
int	size() Get a count of attributes.
int	size(int tag) Get a count the attributes of this type.
static String	toHexString(byte[] buf) Convert a byte buffer to a hex string.
String	toString() Display the attributes in a string.
static byte[]	toUTF8(String s) Convert a string to bytes encoded using UTF8.

Methods inherited from class Object

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

Constructor Detail

AttributeList

public AttributeList()

Construct an empty list.

AttributeList

public AttributeList(Attribute[] list)

Construct a list from an array of attributes.

Parameters:

list - array of attributes.

AttributeList

public AttributeList(AttributeList list)

Construct a list from a list of attributes. The list may be empty or null.

Parameters:

list - AttributeList of attributes.

Method Detail

addAttribute

public final void addAttribute(Attribute att)

Add an attribute to the list. Adds an existing Attribute to the list. If the attribute is null no attribute is added.

Parameters:

att - The attribute to add.

addAttribute

public final void addAttribute(int tag)

Add an attribute with no value to the list. The data portion of the attribute has zero length and the entire attribute will have a length of two.

Parameters:

tag - The attribute tag value.

addAttribute

public final void addAttribute(int tag,
                               byte[] data)

Add an attribute to the list. Adds a new attribute created from the tag value and the byte array.

Parameters:

tag - The attribute tag value.

data - The attribute data

addAttribute

public final void addAttribute(int tag,
                               Date value)

Add an attribute to the list. Adds a new attribute created from the tag value and the Date value. The date will be stored as seconds from the epoch.

Parameters:

tag - The attribute tag value.

value - The attribute Date value

addAttribute

public final void addAttribute(int tag,
                               InetAddress value)

Add an attribute to the list. Adds a new attribute created from the tag value and the string value.

Parameters:

tag - The attribute tag value.

value - The attribute value as an InetAddress.

addAttribute

public final void addAttribute(int tag,
                               int value)

Add an attribute to the list. Adds a new attribute created from the tag value and the integer value.

Parameters:

tag - The attribute tag value.

value - The attribute int value

addAttribute

public final void addAttribute(int tag,
                               int tunnelTag,
                               byte[] data)

Add a tunneling attribute to the list. Adds a new attribute created from the tag value, tunnel tag and the byte array.

Parameters:

tag - The attribute tag value.

tunnelTag - The tunnel tag.

data - The attribute data

addAttribute

public final void addAttribute(int tag,
                               int tunnelTag,
                               InetAddress data)

Add a tunneling attribute to the list. Adds a new attribute created from the tag value, tunnel tag and the byte array.

Parameters:

tag - The attribute tag value.

tunnelTag - The tunnel tag.

data - The attribute data

addAttribute

public final void addAttribute(int tag,
                               int tunnelTag,
                               int data)

Add a tunneling attribute to the list. Adds a new attribute created from the tag value, tunnel tag and the byte array.

Parameters:

tag - The attribute tag value.

tunnelTag - The tunnel tag.

data - The attribute data

addAttribute

public final void addAttribute(int tag,
                               int tunnelTag,
                               String data)

Add a tunneling attribute to the list. Adds a new attribute created from the tag value, tunnel tag and the byte array.

Parameters:

tag - The attribute tag value.

tunnelTag - The tunnel tag.

data - The attribute data

addAttribute

public final void addAttribute(int tag,
                               String value)

Add an attribute to the list. Adds a new attribute created from the tag value and the string value.

Parameters:

tag - The attribute tag value.

value - The attribute String value using UTF8 character encoding.

addAttribute

public final void addAttribute(VendorSpecific vs)

Add an attribute to the list. Adds a VendorSpecific attribute..

Parameters:

vs - VendorSpecific attribute.

clearAttributes

public final void clearAttributes()

Clear all attributes.

createCHAPChallenge

public final void createCHAPChallenge(byte[] plaintextPassword)

Create an 16 byte CHAP-Challenge / CHAP-Password for a plain text password.

Parameters:

plaintextPassword - Password.

createRadiusAttributeBlock

public byte[] createRadiusAttributeBlock()
                                  throws ArrayIndexOutOfBoundsException

Create a RADIUS attribute block from the attribute list. Takes the current list of attributes and returns a single data block suitable for using in the data portion of a Vendor-Specific attribute or a RADIUS packet.

Returns:

byte array of the attribute block. (It may be empty).

Throws:

ArrayIndexOutOfBoundsException - if the attributes are mangled.

See Also:

loadRadiusAttributes(byte[], int, int)

dataSize

public final int dataSize()

Return the current data size of all attributes. This is how large the attribute block will be when constructed. Note: RADIUS packets have a limit of 4096 bytes of payload, twenty of which are consumed by the packet header. If the data block is too long the packet will probably not be accepted by another RADIUS server / client.

Returns:

size of all attributes.

decodeAll

public final void decodeAll(byte[] secret,
                            byte[] authenticator)

Decode all attributes in this AttributeList using a two byte SALT. Cisco® is one vendor that has endorsed this encoding in it's sub-attributes. Other vendors may use this as well. Cisco indicates that the vendor-type (Type field) must be (36₁₀) or their tag value for Cisco-Enc. for an encoded attribute value. Cisco refers to this format as 'Encrypted String VSA Format'.

To decode a single attribute please use saltDecode().

This is an example of an attribute before decoding.

     0                   1                   2
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
 |     Type      |    Length     |  SALT
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
 |     SALT      |   Vendor encoded data ...
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
 

Parameters:

secret - Shared RADIUS secret.

authenticator - RADIUS authenticator.

delete

public final void delete(int type)

Delete an attribute. Deletes a single attribute of a given type. If there are multiple attributes, it deletes the first one found.

Parameters:

type - Attribute type.

deleteAll

public final void deleteAll(int type)

Delete all attributes of a given type.. If there are multiple attributes, it deletes the first one found.

Parameters:

type - Attribute type.

elements

public final Enumeration elements()

Provide an enumeration of attributes.

 for (Enumeration e = aList.elements() ; e.hasMoreElements() ;) {
        Attribute a = (Attribute)e.nextElement();
  }

Returns:

an enumeration of attributes.

encodeAll

public final void encodeAll(byte[] secret,
                            byte[] authenticator)

Encode all attributes in this AttributeList using a two byte SALT. Cisco® is one vendor that has endorsed this encoding in it's sub-attributes. Other vendors may use this as well. Cisco indicates that the vendor-type (Type field) must be (36) for an encoded attribute value. This method can optionally set a new tag value or encode the data leaving the tag value alone. This is described in draft-ietf-radius-saltencrypt-00.txt.

This is what an attribute will look like after encoding.

     0                   1                   2
 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
 |     Type      |    Length     |  SALT
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
 |     SALT      |   Vendor encoded data...
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
 

To encode a single attribute please use saltDecode().

Cisco refers to this format as 'Encrypted String VSA Format'.

Parameters:

secret - Shared RADIUS secret.

authenticator - RADIUS authenticator.

exists

public final boolean exists(int tag)

Determine if an attribute type exists.

Parameters:

tag - Type of attribute.

Returns:

true if the type exists.

findPosition

public final int findPosition(int type)

Find the starting position of an attribute in a RADIUS data block. This has limited use, except for stuffing data into a RADIUS packet after it's been built.

Parameters:

type - Attribute number.

Returns:

position where the attribute starts or -1 if not found.

getAllBinaryAttributes

public final byte[][] getAllBinaryAttributes(int type)

Return all binary attributes of a particular attribute type.

Parameters:

type - attribute type.

Returns:

the binary data for the attribute or null if the attribute isn't found.

See Also:

getBinaryAttribute(int)

getAllStringAttributes

public final String[] getAllStringAttributes(int type)

Return all matching String attributes of the given attribute type.

Parameters:

type - Attribute type.

Returns:

array of Strings or null if none were found.

See Also:

getStringAttribute(int)

getAttributeArray

public final Attribute[] getAttributeArray(int tag)

Get an array of Attributes of a specific type.

Parameters:

tag - Attribute tag.

Returns:

Array of attributes. The array will be empty if the attribute type cannot be found.

getAttributeAt

public final Attribute getAttributeAt(int n)

Get the N'th attribute in the list.

Parameters:

n - position in list.

Returns:

the Attribute a the given position or null if no such attribute.

See Also:

setAttributeAt()

getAttributeList

public final AttributeList getAttributeList(int type)

Get a list of specific attributes.

Parameters:

type - Type of attribute to select.

Returns:

AttributeList of attributes. There may be zero attributes in the list.

getAttributes

public final Attribute[] getAttributes()

Get a list of attributes.

Returns:

list of Attributes.

getBinaryAttribute

public final byte[] getBinaryAttribute(int type)

Return a binary attribute of a given type.

Parameters:

type - attribute type.

Returns:

the binary data for the attribute or null if the attribute isn't found.

See Also:

getBinaryAttribute(int)

getInt

public final int getInt(int type)
                 throws ArrayIndexOutOfBoundsException

Get an integer value (four octets) from an attribute.

Parameters:

type - attribute type.

Returns:

int value.

Throws:

ArrayIndexOutOfBoundsException - if there are no attributes present or the attribute type cannot be found. Use exists() to determine if the attribute exists.

See Also:

size(int)

getIPAttribute

public final InetAddress getIPAttribute(int tag)

Return an IP address from a 4 or 16 byte binary attribute (like NAS-IP-Address).

Parameters:

tag - attribute tag.

Returns:

the IP address or null if the attribute doesn't exist or isn't four bytes long. Only the value for the first attribute found is returned.

getShort

public final int getShort(int type)
                   throws ArrayIndexOutOfBoundsException

Get a short value (two octets) from an attribute. There are no normal attributes with data of this length. It is used internally within the server. It might be used within a Vendor-Specific attribute, but it's not compatible with the RADIUS specification.

Parameters:

type - attribute type.

Returns:

short value as int. Use exists() to determine if the attribute exists.

Throws:

ArrayIndexOutOfBoundsException

getSize

public final int getSize()

Return the size of the current list of attributes. This returns the data size of the resulting attribute block. For a list of general attributes the limit will be the maximum packet size. For Vendor-Specific attributes the limit is 253 data bytes.

Returns:

size of attribute block.

getStringAttribute

public final String getStringAttribute(int type)

Return a particular string attribute. Returns the first string attribute found having the given attribute type.

Parameters:

type - Attribute type to extract.

Returns:

attribute string value or null if the attribute isn't found.

See Also:

getAllStringAttributes(int)

getVendorSpecific

public final VendorSpecific[] getVendorSpecific(int vendor)

Get a list of Vendor-Specific attributes by Vendor Id.

Parameters:

vendor - Vendor Id.

Returns:

An array of Vendor-Specific attributes from a particular vendor. If there are no matching Vendor-Specific attributes the array will be empty.

getVendorSpecific

public final Attribute[] getVendorSpecific(int vendor,
                                           int vendorTag)

Get a list of Vendor-Specific attributes by Vendor Id narrowed down to a particular tag. If multiple Vendor VSA's are present all sub-attributes will be returned. If there are multiple VSA sub attributes with the same tag they will all be included.

Parameters:

vendor - Vendor Id.

vendorTag - Vendor-Specific tag number.

Returns:

An array of Vendor-Specific sub-attributes from a particular vendor with the given tag value. If there are no matching Vendor-Specific attributes or the tag is not present the array will be empty.

Since:

3.35

loadRadiusAttributes

public final boolean loadRadiusAttributes(byte[] dataBlock,
                                          int offset,
                                          int len)
                                   throws ArrayIndexOutOfBoundsException

Creates an attribute list from a raw attribute block. This method doesn't allow empty attributes.

Loads raw data into an attribute list. Useful for loading Vendor-Specific attributes in a TLV format from the Vendor-Specific data.

Parameters:

dataBlock - Radius attribute data block

offset - Offset into buffer

len - length of RADIUS attribute data block.

Returns:

true if long tags were detected.

Throws:

ArrayIndexOutOfBoundsException - when an attribute block is corrupt or there is an empty attribute present.

See Also:

createRadiusAttributeBlock()

loadRadiusAttributes

public final boolean loadRadiusAttributes(byte[] dataBlock,
                                          int offset,
                                          int len,
                                          boolean allowEmpty)
                                   throws ArrayIndexOutOfBoundsException

Creates an attribute list from a raw attribute block perhaps allowing empty attributes.

Loads raw data into an attribute list. Useful for loading Vendor-Specific attributes in a TLV format from the Vendor-Specific data.

Parameters:

dataBlock - Radius attribute data block

offset - Offset into buffer

len - Length of RADIUS attribute data block.

allowEmpty - If true empty attributes are permitted. If false empty attributes will throw an ArrayIndexOutOfBoundsException.

Returns:

true if long tags were detected.

Throws:

ArrayIndexOutOfBoundsException - when an attribute block is corrupt or there is an empty attribute present (not thrown if allowEmpty is set to true).

See Also:

createRadiusAttributeBlock()

mergeAttributes

public final void mergeAttributes(Attribute[] a)

Merge an attribute array with the current AttributeList. The list may be empty or null.

Parameters:

a - Attribute array a.

Returns:

The composite list.

mergeAttributes

public final void mergeAttributes(AttributeList a)

Merge another AttributeList with the current AttributeList. The list may be empty or null.

Parameters:

a - Attribute list a.

mergeAttributes

public final AttributeList mergeAttributes(AttributeList a,
                                           Attribute[] b)

Merge two AttributeLists and return the resulting AttributeList. The lists may be empty or null.

Parameters:

a - Attribute list a

b - Attribute array b

Returns:

The composite list.

mergeAttributes

public final AttributeList mergeAttributes(AttributeList a,
                                           AttributeList b)

Merge two attribute lists and return the resulting new AttributeList. If there's only one list with elements return that one. The lists may be empty or null.

Parameters:

a - Attribute list a.

b - Attribute list b.

Returns:

The composite list.

parseIPAttribute

public static final InetAddress parseIPAttribute(byte[] addr)

Parse an IP address from a IPv4 (4 byte) binary attribute (like NAS-IP-Address).

Returns:

IP address or null if it couldn't be parsed because it isn't at least four bytes long.

parseIPv6Attribute

public static final InetAddress parseIPv6Attribute(byte[] addr)

Parse an IP address from a 16 byte binary attribute (like NAS-IPv6-Address).

Parameters:

addr - Byte representation of an IP address.

Returns:

IP address or null if it couldn't be parsed because it isn't 16 bytes long or IpV6 support isn't available in this Java version.

setAttribute

public final boolean setAttribute(int type,
                                  byte[] data)

Reset the value of an existing attribute. This allows data to be changed without disturbing the order of an attribute. Only the first attribute found will be changed. If the attribute doesn't exist no changes are made.

Parameters:

type - Attribute type.

data - binary data replacement value

Returns:

true if the attribute was found and replaced.

setAttributeAt

public final void setAttributeAt(int n,
                                 Attribute a)

Set the N'th attribute in the list. If the attribute position is out of range the attribute will not be set.

Parameters:

n - position in list.

a - Replacement attribute

See Also:

getAttributeAt()

size

public final int size()

Get a count of attributes.

Returns:

number of attributes.

size

public final int size(int tag)

Get a count the attributes of this type.

Parameters:

tag - attribute tag.

Returns:

The number of attributes of this type.

toHexString

public static final String toHexString(byte[] buf)

Convert a byte buffer to a hex string.

Parameters:

buf - Byte array.

Returns:

Hexadecimal representation.

toString

public String toString()

Display the attributes in a string.

Returns:

string representation of the attributes.

toUTF8

public static final byte[] toUTF8(String s)

Convert a string to bytes encoded using UTF8. In the event that UTF8 is unavailable (highly unlikely) the encoding will be ASCII.

Parameters:

s - String to convert to a UTF8 byte array.

Returns:

UTF8 byte array.