Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Navigation  Back up to About Overview 
  
[+] Expand All
[-] Collapse All

Structured Attributes

Steel-Belted Radius Carrier natively supports structured attributes that contain subattributes. Subattributes 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 subattributes into a RADIUS VSA. In a RADIUS packet, there may be multiple RADIUS VSAs that contain subattributes. The RADIUS VSA, which consists of multiple subattributes, is sometimes referred to as a structured attribute because it contains structured data.

Before Release 7.0, Steel-Belted Radius Carrier only interpreted AVPs and not the subattributes contained within an AVP. For some specific cases, plug-ins were available for Steel-Belted Radius Carrier to copy the subattributes 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 re-assembled the RADIUS AVPs from their contained subattribute 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 subattribute values are automatically parsed and become available to any component within Steel-Belted Radius Carrier that processes RADIUS requests. Similarly, any subattribute 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 subattributes.

Note: This guide uses the following terminology when discussing structured attributes and subattributes: Throughout this guide the term attribute can refer to both the structured attribute and subattribute. 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 subattributes, rather than a conventional simple data type such as an integer. This may be a parent attribute, or it may itself be a subattribute.
  • Subattribute—refers to the data items within a Structured Attribute. While the subattributes 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 subattribute definition files. After the definitions are parsed, they 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.

Note: *.dic dictionary files do not support structured attribute definitions.

XML Format of Dictionary Files

Subattributes definitions in the .jdict files require a specific XML format. Figure 3 shows an example file followed by a description of each XML element.

Figure 3: Example of a Structured Attribute Dictionary File

Example of a Structured Attribute Dictionary
File

The example dictionary in Figure 3 contains three structured attributes: 3GPP2-Diff-Services-Marking, 3GPP2-Service-Option-Profile and 3GPP2-Auth-Flow-Profile-ID.

The following XML elements can be used to define subattributes.

<dictionary> Element

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

In the example in Figure 3, 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 subattributes. Attributes defined as children of the group may occur in any order, or not at all.
    • A sequence is an ordered collection of subattributes. 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>.

Subattribute Elements

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

These children elements each represent a subattribute which may be a child of any structured attribute (top level, or a group or sequence subattribute). <group> and <sequence> indicate that this is a structured subattribute. 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 subattribute, which must be unique only within its parent. The subattribute 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 subattribute 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 subattribute 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:

<integer name='Tariff-Switch-Support' bitwidth='1' default='0’>
<constant value='0' name='False'/>
<constant value='1' name='True'/>
</integer>

Functional Areas That Use Subattributes

Packet Parsing and Formatting

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

When formatting the response packet, created subattributes 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 Subattributes

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
  • Optional SIM authentication module when using Kineto INC
  • Accounting in Steel-Belted Radius Carrier core (ASCII) database, as well as SQL and LDAP external databases
  • Return lists and check lists (configurable through Web GUI and LCI)
  • SQL and LDAP authorization plug-ins (used for optional authentication modules)
  • JavaScript
  • Filters
  • Attribute Maps (used when proxying)

Subattributes in return lists and check lists can be configured using Web GUI or Steel-Belted Radius Carrier LDAP Configuration Interface (LCI).

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

Refer to subattributes in configuration files, using the “ ” notation. For example:

“A.b.c”

Where attribute “A” is a group attribute containing a sequence subattribute “b”, which contains a simple attribute “c”.

Subattributes 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 5, 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.

Note: If you are using the optional Session State Register (High Availability) module, you cannot use subattributes in the sessionTable.ini file to place subattribute values in the sessions table RadAttr fields. This also applies to standalone server.

Single Subattribute Insertion

You do not need to add every subattribute in a tree. Steel-Belted Radius Carrier handles partially defined trees by automatically supplying subattributes that have a default value specified in the .jdict definition files. Additionally, if a subattribute 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 subattribute 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 violates 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 subattribute:

  • 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 subattribute (i.e. an instance of the insertion subattribute 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 subattribute 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 subattribute with a parent attribute, or vice versa.

See Single Subattribute Insertion for a description of how structured (parent) attributes are automatically created when a single subattribute is created.

For more information about the attribute filtering capabilities of Steel-Belted Radius Carrier see filter.ini File in this guide, and see information about setting up filters in the SBR Carrier Administration and Configuration Guide.

Note: Use the Web GUI to maintain settings in the filter.ini file. Do not edit the filter.ini file manually.

Proxy Attribute Mapping

Subattributes 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 subattribute in the incoming packet to a specific realm.

For more information about attribute mapping see the [AuthAttributeMap] and [AcctAttributeMap] sections of proxy.ini File. Also see information about administering proxy RADIUS in the SBR 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 through the LCI or Web GUI.

Note: Structured attributes (VSAs with subattributes) defined in return lists are treated as whole units. They are added to the reply message as a whole unit, rather than their subattributes 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 subattributes "ChildAttrA" and "ChildAttrB".
  • A response already has a copy of "ParentAttr" with subattribute "ChildAttrA", for example from an authentication process.
  • A profile specifies that "ParentAttr" must be added with subattribute "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 about adding a check list or return list to a user entry or profile, and using the LDAP configuration interface, see the SBR Carrier Administration and Configuration Guide.

Using Web GUI to Configure Subattributes in Return Lists and Checklists

Subattributes can be added to return lists and checklists in User and Profile entries. To add a subattribute in a return list or check list using Web GUI, first you add the parent attribute, and then you add the appropriate subattributes using the Add Child button.

For more information about adding a check list or return list to a user entry or profile, see the SBR Carrier Administration and Configuration Guide.

Using the LCI to Define Subattributes in Return Lists and Check Lists

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

For more information about using the LCI to define structured attributes in check lists and return lists, see the SBR Carrier Administration and Configuration Guide.

Javascript

Structured attributes may be specified using the ‘.’ notation in JavaScripts.

See Single Subattribute Insertion for a description of how parent attributes are automatically created when a single subattribute is created.

Converting Previous Attribute Flatteners with Subattributes

Before 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 subattributes 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 subattribute 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 a named attribute, a subattribute may be named using the ‘.’ pathname notation.

See Single Subattribute Insertion for a description of how parent attributes are automatically created when a single subattribute 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 4 shows the 3GPP2 data structure for the 3GPP2-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 4: 3GPP2 Data Definition of the Service-Option-Profile Attribute

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.

SBR Carrier XML Dictionary Definition

Figure 5 shows the definition of the same structure shown in Figure 4, but encoded in the Steel-Belted Radius Carrier XML dictionary definition. Color coding shows the correspondence between data here and the 3GPP2 definition in Figure 4.

Figure 5: XML Dictionary Definition

XML Dictionary 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.
  • Because 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 6 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 6: 3GPP2 Data Structure

3GPP2 Data Structure

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

Figure 7: Log of 3GPP2-Service-Option-Profile Attribute

Log of 3GPP2-Service-Option-Profile
Attribute

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 6, 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 must look like this example:

Because, 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.

Modified: 2017-09-27