doc/dictionaries.txt File Reference

Detailed Description

Dictionaries

The dictionaries define name to number mappings. (See also Dictionary Lookup Functions). For simplicity, the dictionary definitions are compiled to C, and statically linked into the library. This allows them to be used without any run-time initialization. However, the downside is that cannot be modified or updated at run time. That limitation should not affect RADIUS client applications.

The reason for this limiration is that this library implements an "embedded" client. That means that it is capable of sending requests which contain a small list of pre-defined attributes, and receiving responses which contain a small list of pre-defined attributes. Any attributes which are not known at compile time are ignored.

How Dictionaries Work

The list of "known" attributes are defined by the dictionaries. These dictionaries are parsed at compile time to create a "static const" array of definitions (see nr_dict_attrs, radius.h, and dictionaries.c). We recommend customizing the dictionaries to contain only the attributes which are needed. See convert.pl.

This library includes a sample vendor dictionary, called "share/dictionary.vendor". It also includes a minimal Microsoft dictionary, called "share/dictionary.microsoft". No other vendor dictionaries are included. We recommend using the RFC attributes, and possibly a vendor dictionary defined by yourself, using your own private enterprise number. Using attributes from other vendor dictionaries is not recommended.

Note

The dictionary uses attribute names, but these names are relevant only to the local application. The names are never sent "over the wire" to the RADIUS client or server.

File Format

The dictionaries used here are in the FreeRADIUS format, which is an extension of the original Livingston dictionary format. See the FreeRADIUS documentation for a complete description of the format. We give a short description here.

The format consists of a series of lines of text, defined by an initial keyword:

ATTRIBUTE name value type

with the following definitions:

• "name" is a printable name, usually composed of letters, numbers, and the "-" character.
• "value" is a decimal value between 1 and 255.
• "type" is one of the pre-defined RADIUS data types
  • "string" printable text (NR_TYPE_STRING)
  • "integer" unsigned 32-bit integer (NR_TYPE_INTEGER)
  • "ipaddr" IPv4 address (NR_TYPE_IPADDR)
  • "date" 32-bit data, as seconds since January 1, 1970 (NR_TYPE_DATE)
  • "octets" binary data (NR_TYPE_OCTETS)
  • "ipv6addr" IPv6 address (NR_TYPE_IPV6ADDR)
  • "ifid" Interface Id (NR_TYPE_IFID)
  • "ipv6prefix" IPv6 Prefix (NR_TYPE_IPV6PREFIX)
  • "byte" unsigned 8-bit integer (NR_TYPE_BYTE)
  • "short" unsigned 16-bit integer (NR_TYPE_SHORT)

The last two types are included only for compatibility with VSAs defined by certain vendors. We strongly recommend against using them in any new dictionaries.

VENDOR name value format

• "name" is a printable name, usually composed of letters, numbers, and the "-" character.
• "value" is a decimal value between 1 and (2^24)-1
• "format" is an optional format for the VSAs. If left out, the RFC recommended format is used. Otherwise, the allowed formats are:
  • "format=1,1" The RFC recommended format.
  • "format="2,1" Lucent style with 2 octets for the vendor type, and 2 octet for the vendor length. - "format="2,2" Starent style with 2 octets for the vendor type, and 2 octets for the vendor length.
  • "format=4,0" USR style attributes. Not recommended for new VSAs.

We strongly recommend against using the "format=.." variants. Non-standard formats are incompatible and problematic.

A list of Vendor-Specific Attributes is wrapped by BEGIN-VENDOR and END-VENDOR statements:

BEGIN-VENDOR name
ATTRIBUTE ...
ATTRIBUTE ...
END-VENDOR name

This wrapping defines all intermediate attributes as being VSAs for that vendor.

See the file "share/dictionary.vendor" for an example. See also the FreeRADIUS documentation for additional details not discussed here.

Editing the Dictionaries Yourself

The dictionaries should be edited by placing new files into the "share/" directory. We recommend the following procedurex:

• do not edit the file "share/dictionary.txt". The IETF RFC attributes are defined here.
• copy the file "share/dictionary.vendor" to a different file, named for your company. e.g. "share/dictionary.cisco".
• delete the file "share/dictionary.vendor". It is only an example, and is not needed for the library to function.
• edit the vendor-specific file you created, to define:
  • VENDOR name value
  • BEGIN-VENDOR name
  • Any vendor-specific ATTRIBUTE entries
  • END-VENDOR name

Warning

It is forbidden to define attributes in the RFC type space (attributes 1 through 255). Doing so will cause inter-operability problems with all known RADIUS servers. Instead, define attributes as VSAs, in a vendor dictionary, and using your own private enterprise number allocated by IANA via the form at http://pen.iana.org/pen/PenApplication.

Run-Time Extension of the Dictionaries

The library does not support run-time extension of the dictionaries. If you need this functionality, see the FreeRADIUS "libfreeradius-radius" library, which is available under the LGPL license.

Compilation

The files radius.h and dictionaries.c contain definitions for all standard RADIUS attributes. They are automatically created from the files "share/dictionary*", when those files change. The default versions of those radius.h and dictionaries.c have been generated from the default dictionaries. Those files should never be edited directly. Instead, edit the "share/dictionary*" files, and re-build the library.

There is no predefined limit to the number of attributes which can be defined. We recommend defining the RFC standard attributes, and any VSAs that you need. There is usually no need to define a "minimum" set of attributes. Memory is cheap, and it is useful for the library to have definitions for all of the standard attributes.

The library will compile even if no attributes are defined in the dictionaries. However, it will likely not do anything useful. We recommend defining the following attributes at the absolute minimum:

ATTRIBUTE       User-Name                               1       string
ATTRIBUTE       User-Password                           2       string encrypt=1
ATTRIBUTE       Reply-Message                           18      string
ATTRIBUTE       Message-Authenticator                   80      octets

Note that the Vendor-Specific attribute does not need to be defined for VSAs to work. However, any VSAs should still be defined in a vendor dictionary.

Creating a Custom Vendor Dictionary

The process to create a vendor dictionary is relatively straightforward, as the dictionaries are just text files. However, we suggest using the services of Network RADIUS to help design custom dictionaries. The reason is that the technical requirements on the dictionaries can be complex. These requirements are document in RFC 6158, among others.

The team at Network RADIUS wrote those standards, so we are most familiar with them. Following our recommendations ensures that the dictionaries will be compatible with all existing RADIUS servers and clients.

At a high level, the process is as follows:

• ensure that you have a "Private Enterprise Code"
  • this number can be obtained by requesting one from IANA: http://iana.org
• create the dictionary as described above
  • use the Private Enterprise Code as the vendor identifier
• create the attributes
  • Ensure that the names are unique, ideally by using your company name for the prefix. e.g. "Company-Foo" is much better than just "Foo"
  • ensure that the data types for the attributes are taken from RFC 8044
• verify the dictionary with FreeRADIUS
• share the dictionary publicly

The dictionary needs to be shared with all customers who will be using the RADIUS client. The dictionary also should be shared with all major RADIUS server vendors. In practice, this means adding them to FreeRADIUS, and the other vendors will copy the files from there.

The dictionary file format used by FreeRADIUS is simple. Customers and vendors can trivially convert that format to the format required by any other RADIUS server.