Steel Belted Radius Carrier 7.0 Reference Guide > Attribute Processing Files > Structured Attributes

Structured Attributes

Release 7.0 of Steel-Belted Radius Carrier natively supports structured attributes which contain sub-attributes. Sub-attributes, like normal RADIUS attribute-value pair (AVPs), are comprised of the raw encoding of a type field (such as 1 for WiMAX-Release, within the WiMAX-Capability VSA) followed by a length value (such as 5) followed by the value of the attribute (such as "1.2"). In some cases, the sub-attribute may be missing the Type, Length, or both fields. As such, this guide refers to them as sub-attributes.

Sub-attributes are values in a RADIUS packet that are not stored as a RADIUS AVP, or vendor-specific-attribute (VSA), but rather are packed with other sub-attributes into a RADIUS VSA. In a RADIUS packet, there may be multiple RADIUS VSAs that contain sub-attributes. The RADIUS VSA, which consists of multiple sub-attributes, is sometimes referred to as a structured attribute because it contains structured data.

Prior to Release 7.0, Steel-Belted Radius Carrier could only interpret AVPs and not the sub-attributes contained within an AVP. For some specific cases, plug-ins were available for Steel-Belted Radius Carrier to copy the sub-attributes from the AVP container and represent them in the RADIUS request as if they had been received as separate AVPs. In the RADIUS response, Steel-Belted Radius Carrier would re-assemble the RADIUS AVPs from their contained sub-attribute values. This process was known as packet flattening/unflattening.

The dictionary mechanism of Steel-Belted Radius Carrier has been extended to allow for XML declaration of structured AVP contents. When an AVP with an associated structure definition is received, its internal sub-attribute values are automatically parsed and become available to any component within Steel-Belted Radius Carrier that processes RADIUS requests. Similarly, any sub-attribute values that are populated into the RADIUS response are formatted as part of the structured RADIUS AVP according to the same XML structure definition.

If you previously used the packet flattening/unflattening method, we recommend that you migrate to using sub-attributes.

NOTE: This guide uses the following terminology when discussing structured attributes and sub-attributes: Throughout this guide the term attribute can refer to both the structured attribute and sub-attribute. A distinction has been made only where necessary. Attribute—used to represent a standard RADIUS attributes in the packet. Structured or parent attribute—used to describe an attribute that contains sub-attributes, rather than a conventional simple data type such as an integer. This may be a parent attribute, or it may itself be a sub-attribute. Sub-attribute— refers to the data items within a Structured Attribute. While the sub-attributes are frequently in TLV format, occasionally they are missing Type, Length, or both.

Structured Attribute Dictionary Definitions

The existing dictionary definitions of Steel-Belted Radius Carrier have been extended to support structured attributes. Existing dictionary definitions are defined in .dct files, while structured attribute definitions are defined in .jdict files. Like the initialization files, the .jdict files are loaded at startup time. These dictionary files identify the structured attributes Steel-Belted Radius Carrier expects to receive in RADIUS requests from a specific type of device, and the structured attributes that Steel-Belted Radius Carrier includes when sending a RADIUS response to a specific type of device.

The .jdict definition files reside in the radiusdir/subattributes directory. All files in this directory, ending in .jdict, are parsed by Steel-Belted Radius Carrier as sub-attribute definition files. Once parsed, the definitions are merged into the .dct definitions. Each structured attribute definition must correspond to a .dct definition.

NOTE: Structured attributes must be defined to be in hexadecimal format in the .dct file.

XML Format of Dictionary Files

Sub-attributes definitions in the .jdict files require a specific XML format. Figure 7 shows an example .jdict file followed by a description of each XML element.

Figure 7: Example Structured Attribute Dictionary File

The following XML elements can be used to define sub-attributes.

<dictionary> Element

The top level element must be tagged <dictionary>, and must specify the name of the .dct file being augmented with the sub-attribute details in its name attribute.

In the example in Figure 7, the name of the dictionary file is radius.dct.

The only allowable child of the <dictionary> element is <attribute>.

<attribute> Element

The only allowable child of the <dictionary> element is the <attribute> element. You may have multiple <attribute> elements for each <dictionary> element, each of which provides supplemental detail for a structured attribute in the .dct file (which must be of type hexadecimal).

Mandatory XML attributes of <attribute> elements are:

• name: the identifying name of the attribute, matching that in the .dct file. This must be unique across all dictionaries.
• vendor: the vendor id for the attribute if it is a VSA, which is the typical case.
• type: the integer type code of the attribute (this is unique for a given vendor)
• format: either a sequence or group, specifying the structure of the attribute:

• A group is an unordered collection of sub-attributes. Attributes defined as children of the group may occur in any order, or not at all.
• A sequence is an ordered collection of sub-attributes. Each child attribute must occur in the final output, in the defined order.

Optional XML attributes of <attribute> elements are:

• hasContinuationFlag: indicates that this attribute starts with a continuation octet, where the payload of the attribute may be split over multiple VSAs. This is currently only used in WiMAX attributes.

The allowable children elements of the <attribute> element include: <group>, <sequence>, <integer>, <string>, <octets>, <IPv4>, <IPv6>.

Sub-attribute Elements

The allowable children elements for the <attribute> element include: <group>, <sequence>, <integer>, <string>, <octets>, <IPv4>, <IPv6>.

These children elements each represent a sub-attribute which may be a child of any structured attribute (top level, or a group or sequence sub-attribute). <group> and <sequence> indicate that this is a structured sub-attribute. The other elements represent simple data types. They all share common configuration and may contain the following attributes:

• name (mandatory): indicates the identifying name of the sub-attribute, which must be unique only within its parent. The sub-attribute is addressable using the full pathname to this attribute, analogous to files and directories in a file system.
• type (optional): if present, indicates the type code at the start of this attribute's encoding. By default, if a type code is specified, it is assumed that the attribute encoding also includes a length octet.
• hasLength (optional): used to indicate an unusual attribute encoding with either a type code without a length code, or a length code without a type code. Default: if a type is present, the default is true, otherwise, the default is false.
• isMultiple (optional): indicates whether this sub-attribute may appear multiple times. Default false.
• default (optional): used to indicate the default value for this attribute. This is of use in a <sequence> parent, where values are required for each child. In some cases, a sequence contains anonymous padding bits or octets, this allows the padding value to be specified.

<integer> elements may have the attribute bitwidth, which indicates the size of the integer in bits. By default, this is 32, representing a 4 octet integer. It may be any number from 1 through 32. When a <sequence> attribute has unused bits or octets, define them as anonymous integer elements with default="0".

<string> and <octet> elements may have the attribute length, to indicate they are of a specified fixed length.

Any of these elements are allowable children of <group> or <sequence> elements. The other, simple sub-attribute types, may only have <constant> child elements.

<constant>

The <constant> element defines, in its name and value attributes, a named value which a simple attribute may have, for example:

Functional Areas That Use Sub-attributes

Packet Parsing and Formatting

A structured attribute, with a definition in the .jdict file, is parsed into sub-attributes, and their hierarchical structure is visible if the packet is logged in the Steel-Belted Radius Carrier log file. If the sub-attribute parsing fails, messages are output, and the sub-attributes are not available; only the parent attribute has its raw binary payload.

When formatting the response packet, created sub-attributes are processed, but any error encountered prevents the packet from being sent. Steel-Belted Radius Carrier is not able to determine the severity, or consequences of the error, so packet formatting must fail outright. Examples of errors are integer attribute value overflows, or sequence attributes where absent children have no defined default values.

Features that Support the Use of Structured and Sub-attributes

In general, where standard RADIUS attributes can be defined, structured attributes may also be defined. The following features of Steel-Belted Radius Carrier can use structured attributes:

• Optional WiMAX Mobility module
• Accounting in Steel-Belted Radius Carrier core (ASCII) database, as well as SQL and LDAP external databases
• Return lists and check lists (configurable through SBR Administrator and LCI)
• SQL and LDAP authorization plug-ins (used for optional authentication modules)
• JavaScript
• Filters
• Attribute Maps (used when proxying)
• Optional SIM authentication module when using Kineto INC

Sub-attributes in return lists and check lists can be configured using SBR Administrator or through the Steel-Belted Radius Carrier LDAP Configuration Interface (LCI).

However, most of the features that use sub-attributes are configured using Steel-Belted Radius Carrier configuration files. Refer to the appropriate chapter in the Steel-Belted Carrier Administration and Configuration Guide for configuring these features.

Refer to sub-attributes in configuration files, using the "." notation. For example:

"A.b.c"

Where attribute "A" is a group attribute containing a sequence sub-attribute "b", which contains a simple attribute "c".

Sub-attributes are addressable only by their full pathname, which must include all interim group or sequence attributes.

For example, in the dictionary file shown in Figure 9, the individual service option value is addressed using the following "." notation:

3GPP2-Service-Option-Profile.Service-Options.Service-Option.Value

In this example you see the integer "Value" attribute within the Service-Option sequence attribute, within the Service-Options group attribute, within the structured (parent) 3GPP2-Service-Option-Profile group attribute.

Single Sub-attribute Insertion

You do not need to add every sub-attribute in a tree. Steel-Belted Radius Carrier handles partially defined trees by automatically supplying sub-attributes that have a default value specified in the .jdict definition files. Additionally, if a sub-attribute is added that does not have a suitable parent or group defined, Steel-Belted Radius Carrier automatically creates one.

Steel-Belted Radius Carrier can create structured (parent) attributes automatically. When an individual sub-attribute is to be created (for SQL authentication or accounting, LDAP authentication, JavaScripting, or filtering), the associated structured (parent) attribute is automatically created as needed, either because it does not yet exist, or because to use an existing one would violate the isMultiple=false status of an attribute in the .jdict definition.

Steel-Belted Radius Carrier uses the following algorithm to decide which structured attribute to use, or create, to hold the sub-attribute:

• Obtain a candidate (parent) structured attribute, if possible: Starting at the top-most attribute type, find the final instance (if any) in the packet. Within that parent attribute, find the final instance of the next level attribute, and so on, until no instance is found or Steel-Belted Radius Carrier has reached the level of the parent attribute and obtained a candidate.
• If a candidate (parent) structured attribute is found, but cannot accept another instance of the insertion sub-attribute (i.e. an instance of the insertion sub-attribute already exists, and it is not declared to be multi-valued), discard the candidate parent.
• If no candidate (parent) structured attribute exists, create a new one.
• Add the insertion sub-attribute to the (parent) structured attribute that was obtained.

Attribute Filtering

Structured attributes may be specified in attribute filters in the same way standard RADIUS attributes are specified. Attribute filters allow you to set up rules for filtering attributes into and out of RADIUS packets. You cannot replace a sub-attribute with a parent attribute, or vice versa.

See Single Sub-attribute Insertion for a description of how structured (parent) attributes are automatically created when a single sub-attribute is created.

For more information on the attribute filtering capabilities of Steel-Belted Radius Carrier see Chapter 13, Setting up Filters in the Steel-Belted Radius Carrier Administration and Configuration Guide and filter.ini File in this guide.

NOTE: Use the SBR Administrator to maintain settings in the filter.ini file. Do not edit the filter.ini file manually.

Proxy Attribute Mapping

Sub-attributes may be named in the attribute mapping functionality when proxy routing is configured on the Steel-Belted Radius Carrier server. Attribute mapping allows you to map the presence, absence, or specific value of an attribute or sub-attribute in the incoming packet to a specific realm.

For more information on attribute mapping see the [AuthAttributeMap] and [AcctAttributeMap] sections of proxy.ini File and Chapter 8, Administering Proxy RADIUS in the Steel-Belted Radius Carrier Administration and Configuration Guide.

Structured Attributes in Return Lists and Check Lists

A check list attribute is an item of information that must accompany a request for connection before the connection can be authenticated. A return list attribute is an item of information that Steel-Belted Radius Carrier includes in the Access-Accept message when a connection request is approved.

Structured attributes can be defined as a whole in return lists and check lists. The return lists and check lists can be defined either through the LCI, or by using SBR Administrator.

NOTE: Structured attributes (VSAs with sub-attributes) defined in return lists are treated as whole units. They are added to the reply message as a whole unit, rather than their sub-attributes being added individually to any existing response VSAs. In this way they are treated just as unstructured VSAs. For example: Attribute "ParentAttr" is defined as being a multivalue return list attribute, with possible sub-attributes "ChildAttrA" and "ChildAttrB". A response already has a copy of "ParentAttr" with sub-attribute "ChildAttrA", for example from an authentication process. A profile specifies that "ParentAttr" must be added with sub-attribute "ChildAttrB". The result is a response with two ParentAttr structured attributes: ParentAttr ChildAttrA ParentAttr ChildAttrB The result is not be a response with a single ParentAttr: ParentAttr ChildAttrA ChildAttrB

For more information see "Adding a Check List or Return List Attribute to a User", "Adding a Check List or Return List Attribute to a Profile", and Chapter 24, Using the LDAP Configuration Interface in the Steel-Belted Radius Carrier Administration and Configuration Guide.

Using SBR Administrator to Configure Sub-attributes in Return Lists and Check Lists

Sub-attributes can be added to return lists and check lists in User and Profile entries. To add a sub-attribute in a return list or check list using SBR Administrator, first you add the parent attribute, and then you add the appropriate sub-attributes using the Add Child button.

For more information see "Adding a Check List or Return List Attribute to a User" and "Adding a Check List or Return List Attribute to a Profile" in the Steel-Belted Radius Carrier Administration and Configuration Guide.

Using the LCI to Define Sub-attributes in Return Lists and Check Lists

The LCI (LDAP Control Interface) has been extended to facilitate the definition of sub-attributes in check lists and return lists in XML format. When defining sub-attributes using the LCI, you must define the entire structured attribute hierarchy in XML format. Individual sub-attributes cannot be defined in the XML format.

For more information see Example of Configuration and Usage of a Structured Attribute, the example of LCI Encoding, and "Using the LCI to Define Structured Attributes in Check Lists and Return Lists" in the Steel-Belted Radius Carrier Administration and Configuration Guide.

Javascript

Structured attributes may be specified using the '.' notation in JavaScripts.

See Single Sub-attribute Insertion for a description of how parent attributes are automatically created when a single sub-attribute is created.

Converting Previous Attribute Flatteners with Sub-attributes

Prior to Release 7.0, Steel-Belted Radius Carrier used attribute flattening as an interim solution for handling structured attributes, specifically for using Kineto INC and 3GPP2 Rev.A attributes. This flattening capability handled specific attributes by extracting sub-attributes and putting their values into specially defined structured (parent) attributes, in the Steel-Belted Radius Carrier RADIUS dictionary. For example, the attribute: 3GPP2-Service-Option-Profile. Max-Service-Links was copied to the structured attribute Funk-3GPP2-Max-Service-Conns. Conversion to using the new sub-attribute capability is simply a matter of replacing the attribute name Funk-3GPP2-Max-Service-Conns with 3GPP2-Service-Option-Profile. Max-Service-Links in the configuration.

For more information see Attribute Handling Methods.

Plug-in Attribute Access

Where a plug-in (SQL or LDAP) allows the definition of an named attribute, a sub-attribute may be named using the '.' pathname notation.

See Single Sub-attribute Insertion for a description of how parent attributes are automatically created when a single sub-attribute is created.

Example of Configuration and Usage of a Structured Attribute

The following example compares the 3GPP2 data definition and the Steel-Belted Radius Carrier .jdict definition for the same attribute.

3GPP2 Data Definition

Figure 8 shows the 3GPP2 data structure for the Service Option Profile attribute.

It encodes a total number of connections/links available, followed by a list of Service Option types and the maximum number of instances for that service type.

Figure 8: 3GPP2 Data Definition of the Service-Option-Profile Attribute

The first two rows (8 octets) are standard RADIUS VSA headers.

• Type is 26, as it is for all RADIUS VSAs
• Vendor-ID is 5535 the defined identifier for 3GPP2 VSAs
• Vendor-Type is 74, the identifier specified by 3GPP2 for the Service Option Profile attribute
• Length and Vendor-Length depend upon the payload.

The remaining rows are the payload of this attribute. They consist of:

• a mandatory 4-octet integer "Maximum service connections/Link Flows total", followed by
• any number of instances of the final line of 4 octets, each of which represents one service option, and its associated maximum.

.jdict Data Definition

Figure 9 shows the definition of the same structure shown in Figure 8, but encoded in the Steel-Belted Radius Carrier 3GPP2.jdict file. Color coding shows the correspondence between data here and the 3GPP2 definition in Figure 8.

Figure 9: .jdict Data Definition

• The attribute is defined as a sequence, because the order of the data is fixed; the Max-Service-Links must appear before the instances of the Service-Option block.
• Max-Service-Links is just a simple 4-octet integer
• A group Service-Options is defined to specify the structure where the Service-Option block can occur multiple times. Typically a group contains many children, any of which may occur. In this case, there is only one child type - "Service-Option". This group is purely logical - it does not correspond to any binary data at the physical level.
• The Service-Option sequence is defined with "isMultiple=true", to specify that it can occur multiple times in the Service-Options group.
• Since the Service-Option consists of a type (1), length (4), and two single-octet data values (the value of the Service Option, and its count), it is defined as a sequence of two integers with a type value.

Example Data

Figure 10 shows the example data for this structure in reference to the 3GPP2 data definition. It contains Max-Service-Links with value 128 (0x80), and three Service Option values, with Values 30, 10, 20, with Max-Count 60, 20, 40 respectively.

Figure 10: 3GPP2 Data Structure

In the Steel-Belted Radius Carrier log, with log level set to 2, you would see the instance of the attribute example shown in Figure 10 logged as:

The log shows both the decoded values, and the binary payload encoding, so the same data appears in multiple forms.

In the packet, the whole VSA, including its RADIUS header, indicated by the first two lines shown in Figure 10, appears as:

LCI Encoding

To include the above data as a return list attribute using the Steel-Belted Radius Carrier LCI, the data format is:

The XML must be concatenated onto one line for an LCI command. For example, to add the attribute to the return list for the native user "nativeUserName", the XML would look like this example:

Since, in the .jdict definition, the Max-Count attribute has a default of '0', it is allowable to omit it, if the default is the desired value.

NOTE: When using the LCI command line utilities such as ldapquery, XML values for structured attributes are displayed encoded in a non-readable format. This encoding is base64 encoding which can be decoded with many command line or web-based utilities. Alternatively, the problem can be avoided by using a graphical LDAP client.