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

SSR Datatypes

This section describes the datatypes that Session State Register supports.

Note: We do not support any datatype not explicitly addressed in this document. This applies to datatypes themselves, sizes of datatypes, character sets, and their collations.

Definitions

Data in a RADIUS attribute may be one of six datatypes:

  • NULL: No data at all; absence of data.
  • INT: Data that is either a bare (numerical, counting) measure or a semantic (enumeration, ordinal) value, representing one value out of a specific set of values.

    Examples: 42 (measuring a person's age in years); 0 (as a stand-in for false).

  • ADDR: IPv4 addresses. These are ultimately 32-bits quantities as far as networks are concerned, but are usually represented as integers or as dotted-quad strings. Example: 10101100000110010110000101001101 = 0xac19614d = 2,887,344,461 = 172.25.97.77.
  • TIME: Seconds elapsed in the UNIX epoch, commencing at 00:00:00 (the stroke of midnight) on the morning of January 1, 1970 UTC. Example: 1,142,370,727 = 2006-03-14T16:12:07-0500 = 4:12:07PM Eastern Daylight Time, March 14, 2006.
  • CHAR: Information expressed in natural languages. Example: Administration Building.
  • BYTE: Encoded data. Example: Encrypted communications.

Table 28 summarizes these data types:

Table 28: Terminology for Datatypes

This Document

RADIUS Spec

SQL

Core SBR & SBR Dictionaries

SBR/SSR Implementation

NULL

(absent)

NULL

RAD_TYPE_CONSTANT

(absent)

INT

integer
(32-bit unsigned, big-endian)

TINYINT
SMALLINT
MEDIUMINT
INT

SIGNED or UNSIGNED

RAD_TYPE_INTEGER, RAD_TYPE_INT1 RAD_TYPE_HEX4 RAD_TYPE_IPXADDR_POOL
integer
signed-integer
int1
int4
hex1
hex4
ipxaddr-pool

FieldFormat_UInteger, FieldFormat_SInteger

ADDR

address (32-bit)

INT

UNSIGNED

RAD_TYPE_IPADDR, RAD_TYPE_IPADDR_POOL
ipaddr
ipaddr-pool

FieldFormat_UInteger

TIME

time (32-bit)

TIMESTAMP

RAD_TYPE_TIME
time

FieldFormat_UInteger

CHAR

text (utf8, 0-255 bytes)

CHAR
VARCHAR

RAD_TYPE_STRING
RAD_TYPE_STRINGNZ
string
stringnz

FieldFormat_String, FieldFormat_StringFixed

BYTE

string
(0-255 bytes)

BINARY
VARBINARY

RAD_TYPE_HEXSTRING, RAD_TYPE_IPV6ADDR, RAD_TYPE_IPV6PREFIX, RAD_TYPE_IPV6INTERFACE
hexadecimal
ipv6addr
ipv6prefix,
ipv6interface

FieldFormat_Raw, FieldFormat_RawVar

System Field Datatypes

The datatypes for the System fields have already been specified as listed in Table 28. Some are fixed, and some are customizable.

RadAttr Fields

A RadAttr field declared in sessionTable.ini as RadAttrFieldName = Radius-Attribute-Name associates a CST field (RadAttrFieldName) with a RADIUS attribute (Radius-Attribute-Name), that involves two datatypes:

  • The RADIUS attribute (Radius-Attribute-Name) has a RADIUS datatype specified by the dictionary in which Steel-Belted Radius Carrier finds it.
  • The CST field (RadAttrFieldName) has a SQL datatype determined by the field's declaration in the CST schema (CurrentSessions.sql).

These two datatypes must match or be compatible with one another so the RADIUS datatype can be mapped or converted to the SQL datatype. In this context:

  • Match—A natural /primary/canonical/favorite mapping, as specified in Table 29.
  • Compatible—An unnatural/secondary/conventional/formatting conversion, as specified in Table 29.

Take care to coordinate datatypes to avoid processing errors.

Matching/Natural Datatype Mappings

Table 29 lists the natural datatype conversions from RADIUS datatypes to SQL datatypes, together with the usual way to display values stored in the database using the SQL SELECT command as implemented in ShowSessions.sh.

Table 29: Matching/Natural Mappings

RADIUS Datatype

SQL Datatype

SQL SELECT Display Command

(absent)

NULL

Conventionally displayed in Steel-Belted Radius Carrier as (n u l l) (9 characters, 3 of which are spaces,).

integer

INT UNSIGNED

Supported natively, for example (with auxiliary formatting options, such as commas for thousands separators, available):

SELECT RadAttrFieldName FROM CurrentSessions;

In the case of enumerative values, you should use the CONCAT() built-in function to display the name of the enumerated value, followed by the integer value in parentheses.

address

INT UNSIGNED

The standard dotted-quad string notation for IPv4 addresses is available using the INET_NTOA() built-in function:

SELECT INET_NTOA (RadAttrFieldName) AS
RadAttrFieldName FROM CurrentSessions;

time

TIMESTAMP

Supported natively, for example (with auxiliary formatting options available):

SELECT RadAttrFieldName FROM CurrentSessions;

text

[VAR]CHAR

Supported natively. Make the CHAR nature of the data explicit by surrounding it with double quotation marks:

SELECT CONCAT('\"', RadAttrFieldName , '\"') AS RadAttrFieldName FROM CurrentSessions;

string

[VAR]BINARY

Supported natively. Make the BYTE nature of the data explicit by surrounding it with single quotation marks:

SELECT CONCAT('\'', LCASE(HEX( RadAttrFieldName )), '\'') AS RadAttrFieldName FROM CurrentSessions;

Sample ShowSessions.sh Report

Figure 15 shows sample output of ShowSessions.sh:

Figure 15: ShowSessions.sh Output

CurrentSessions:
+ -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- + (1)
CORE
      UniqueSessionId: 'e86cb6d3717ab5331c68e6bf2b8ec6ef'x
         CreationTime: 2017-08-17 12:44:58 (TZ=+00:00)
       ExpirationTime: 2017-08-18 12:44:58 (TZ=+00:00)
          Ipv4Address: 10.212.10.17
           IpAddrPool: (n u l l)
              NasName: "LOCALHOST"
               Status: Active (2)
    UserConcurrencyId: (n u l l)
         MobileIpType: 0
         3gpp2ReqType: 0
      WimaxClientType: 0
       WimaxAcctFlows:
          Ipv6Address: “3333:0000:0000:0000:0000:0000:0000:4444”
FEATURE
         AcctAutoStop: (n u l l)
       ClassAttribute: '00'x
OPTIONAL
             UserName: "test"
        AcctSessionId: "1502973868T2gpu"
        TransactionId: (n u l l)
          NasPortType: NULL
              NasPort: 0
     CallingStationId: "somecaller"
      CalledStationId: (n u l l)
  MobileCorrelationId: (n u l l)
      Ipv6InterfaceId: (n u l l)
           Ipv6Prefix: NULL
       NasIpv4Address: 127.0.0.1
       NasIpv6Address: (n u l l)
RADATTR
       WimaxSessionId: (n u l l)
   AcctMultiSessionId: (n u l l)
    FunkOuterUserName: (n u l l)
PRIVATE
+ -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- + (end) 

These notes explain the report shown in Figure 15:

  • The current date reported by the admin host where ShowSessions.sh is running is printed.
  • Each CST record is separated within “+---…---+” header and footer delimiters. Each CST record is numbered (beginning at 1) at its header delimiter, and the end of the printout is marked by an unnumbered footer delimiter. (In Figure 15, the CST contains only a single session.)
  • By default, displayed records are sequenced primarily by CreationTime, then by ExpirationTime, and then by Ipv4Address. You can customize this by changing the SQL ORDER BY clause in ShowSessions.sh.
  • The Core, Feature, Optional, RadAttr, and Private fields are grouped into separate titled sections, for the convenience of the reader. You can change this or remove titles by modifying the ShowSessions.sh script.
  • The System field names have been made easier to read by removing their Sbr_ prefixes, and the displayed names of the Admin fields have been customized to include the prefix My.
  • The various kinds of SQL SELECT displays mentioned in Table 29 are shown:
    • NULL values are shown for 10 fields. To eliminate fields that are always NULL (such as disabled Feature fields), comment them out in ShowSessions.sh so they do not appear in the printout.
    • Raw INT data for the NasPort and MyRadAttrField1 fields is displayed. (Note the formatting of the separators in NasPort. You can customize this.)
    • Enumerative INT data for the IpAddrPool, Status, and NasPortType fields is displayed.
    • ADDR data is displayed for the Ipv4Address field.
    • TIME data is displayed for the CreationTime and ExpirationTime fields.
    • CHAR data is displayed for the NasName, UserName, AcctSessionId, and MyRadAttrField2 fields.
    • BYTE data is displayed for the UniqueSessionId, TransactionId, and MyRadAttrField3 fields.

Concerning the definitions of the RadAttr fields in this example:

  • The SQL declaration of the RadAttr fields is:
    RadAttrField1 INT UNSIGNED DEFAULT NULL,
    RadAttrField2 VARCHAR(24) CHARSET utf8 COLLATE utf8_general_ci DEFAULT NULL,
    RadAttrField3 BINARY(24) DEFAULT NULL,
  • The sessionTable.ini file is:
    [AuthRequest]
    RadAttrField1 = NAS-Port
    RadAttrField2 = User-Name
    RadAttrField3 = User-Password
    [AuthResponse]
    [AcctRequest]
    [AcctResponse]

    The definition of the RadAttrField1 has the same value as the NAS-Port field, though the latter has some formatting applied to it (at the natural display level, not at the unnatural storage level; see the following subsection).

    The definition of RadAttrField2 is the same as User-Name, except that the latter has been processed by Steel-Belted Radius Carrier (as mentioned previously).

    The definition of RadAttrField3 demonstrates the kind of padding that occurs with SQL BINARY fields. Had it been declared VARBINARY(24), the padding zeros would not have appeared.

Note: The RADIUS User-Password attribute is encrypted (hence, BYTE) data.

Compatible/Unnatural Datatype Conversions

In addition to the matching/natural mappings defined previously, Steel-Belted Radius Carrier SSR supports the compatible/unnatural conversions listed in Table 30.

Table 30: Compatible/Unnatural Conversions

RADIUS Datatype

SQL Datatype

INT UNSIGNED

TIMESTAMP

[VAR]CHAR

[VAR]BINARY

integer

Natural Match

Coerce

Base10

Base256

address

Natural Match

Coerce

Dotted Quad

Base256

time

Coerce

Natural Match

ISO8601

Base256

text

Length

None

Natural Match

Coerce

string

Length

None

Hex

Natural Match

This list further explains the values in Table 30:

  • Coerce—Re-interpret the underlying bits of the RADIUS datatype as if they were the underlying bits of the corresponding SQL datatype.
  • Length—Length in bytes (not in characters in the CHAR case). A terminating NULL byte, if any, is not counted. This conversion is supported for its helpfulness in checking database-storage padding and truncation issues.
  • Base10—Express an integer in the usual decimal notation, using the Unicode Basic Latin characters 0…9, possibly preceded by a minus-sign.
  • Dotted Quad—Conventional notation for IPv4 addresses.
  • ISO8601 (RFC 3339)—Conventional international standard format YYYY-MM-DDThh:mm:ssZ. Both T and Z are required elements. The Z indicates UTC; if it is not present, the interpretation defaults to local time zone.
  • Hex—Conventional mapping of BYTE strings to hex-strings (character-strings of even length, using only the characters [0-9a-fA-F]).
  • Base256—Conventional mapping of 32-bit (big-endian) INT values to 4-byte BYTE strings: write the given number in the form N = A 2563 + B 2562 + C 2561 + D 2560, then use the sequence A/B/C/D as the base-256 encoding, suppressing leading zeros. This is, in essence, a kind of coercion, if we posit a 4-byte big-endian environment.
  • None—The potential conversion is not supported.

Note: There is a major conceptual difference between the preceding section and this one. We highlight the address>dotted-quad conversion for the sake of concreteness, but the argument applies equally well to integer>base-10, time>ISO8601, and string>Hex.

In the natural mechanism, IPv4 addresses are stored in the CST as INT UNSIGNED values, and the dotted-quads are merely used as a device for displaying the values to users. This is how the Sbr_Ipv4Address System field is implemented. But in the unnatural case, the IPv4 address is stored in the CST itself as dotted-quad CHAR data.

Other things being equal, the natural scheme is preferred because SQL’s extensive built-in facilities and stored procedures are adequate for all data-manipulation and data-display tasks, and are much more flexible than our unnatural scheme. The unnatural scheme is supported with a certain class of tools that foster datatype conflation. This is traditional for SQL-based programming, and SQL itself includes convenience tools of this class. For example, MySQL permits the (64-bit) number 20060314161207, the character-string 20060314161207, and the timestamp 2006-03-14 16:12:07 to be used interchangeably.

Customizing Datatypes and Data Sizes

You have some latitude for customizing datatypes (including character sets and collations) and sizes in many System and RadAttr CST fields. This section describes the rules for modification.

To understand the problem, consider the Sbr_NasName field, but pretend for simplicity that it always contains the contents of a NAS-Identifier RADIUS attribute. According to RFC 2865, the NAS-Identifier attribute has a BYTE datatype, and can have any size from 0 through 255 bytes. Consequently, you can safely declare the Sbr_NasName field to be [VAR]BINARY(255). However, in most environments, NAS-Identifiers are relatively short and human-readable; that data value is the underlying byte-string of an encoded character-string. In such environments, declaring Sbr_NasName to be [VAR]BINARY(255) is wasteful in terms of database storage and network bandwidth used and less useful because the resulting string is unreadable. In such cases, you might declare Sbr_NasName to be VARCHAR(24) using UTF8 text strings.

  • For System Core and Feature fields, use a datatype and size that guarantees full fidelity of information (no semantic data loss). If you use an inappropriate datatype or size, Steel-Belted Radius Carrier SSR can fail in unpredictable ways because the data in question is critical to stable processing. If the data in a System Core or Feature field is unreliable, Steel-Belted Radius Carrier might not work correctly.
  • If Steel-Belted Radius Carrier does not depend on the data in question, a less restrictive rule applies. For example, consider the Sbr_UserName field. Again, the RADIUS RFC guarantees that [VAR]BINARY(255) is safe. You can declare the Sbr_UserName field as VARCHAR(24) using Latin1 text strings, but might lead to problems if users want to use Japanese names. However, if the network has no lines in Japan, very few customers might be affected, and the declaration is not a problem.

To apply these rules, be familiar with the RADIUS RFCs and the network environment.

Character Sets and Collations

The SSR database supports many character sets (charsets). Steel-Belted Radius Carrier SSR sites can use any charset and any associated collation supported by the SSR database that does not use the NULL byte in its encoding. Examples of permissible charsets are: ASCII, Latin1, and UTF8. A non-example is UCS2 (which is the straight-forward 2-byte encoding of the Basic Multilingual Plane (BMP), Unicode U+0000…U+FFFF).

Because charsets in the SSR database can have an expansion factor (1, 2, or 3) associated with them, specifications for field sizes can be misleading. For example, if a field in the CST schema is declared VARCHAR(7) CHARSET utf8, then the field is guaranteed to hold up to seven Unicode characters encoded in UTF8. Because UTF8 has an expansion factor of 3, a VARCHAR(7) field can hold up to 3x7 = 21 bytes of information.

Truncation and Padding

The SQL datatypes [VAR]CHAR(N) and [VAR]BINARY(N) reserve a fixed number of bytes, called the field's storage size, for every stored value in NDB. The storage size for [VAR]CHAR is the charset expansion factor times N; the storage size for [VAR]BINARY is N. Steel-Belted Radius Carrier always presents exactly the full storage size of data to NDB.

In cases where a field value is less than the storage size, Steel-Belted Radius Carrier pads the value out to the full storage size before presenting it to NDB for storage. The padding value is the SPACE character in the [VAR]CHAR case and the NUL byte in the [VAR]BINARY case.

In cases where a field value is greater than the storage size, Steel-Belted Radius Carrier truncates it to the field storage size. No log file messages are written if data is truncated.

The maximum storage size for any field in the CST is 4096 bytes, large enough for any System field or natural RadAttr field. This is sufficient to store all the raw data carried in any RADIUS attribute value, even if the whole RADIUS packet consists of one large multi-value attribute.

Small Integers

Truncation and padding are not used with INT numerical data. Because the RADIUS specification discusses only 4-byte INT data, you can always safely declare a RadAttrFieldName in the CST schema as an INT.

If you are certain that, in your network, all values of RadAttrFieldName fit into a TINYINT (1 byte), SMALLINT (2 bytes), or MEDIUMINT (3 bytes), you can declare RadAttrFieldName to be of an appropriate type in the SQL schema. However, if an illegal overflow value is presented to Steel-Belted Radius Carrier for storage in a field that is too small, the value that Steel-Belted Radius Carrier stores is the largest value that the field will hold (0xff = 255, 0xffff = 65,535, 0xffffff = 16,777,215 respectively). No log file message is generated. As a general rule, do not use TINYINT, SMALLINT, or MEDIUMINT unless you are sure the network can tolerate this potential loss of information.

Signed Integers

In the original RADIUS specifications, all integer attributes were specifically unsigned. Recent usages have started to use signed attributes. For this reason, our implementation allows RadAttrFieldNames to be specified as SIGNED fields in the CST schema. Steel-Belted Radius Carrier SSR supports this only as a natural facility: you must declare the sign of SQL INT datatypes correctly. There are no (natural or unnatural) conversions between signed and unsigned integers.

For signed INT quantities, you can use TINYINT, SMALLINT, or MEDIUMINT in SSR database schema declarations if you know the values in your network can fit into these smaller-sized fields. If a value too large for a field is presented to SBR Carrier for storage, SBR Carrier stores the largest possible value (that is, most-positive, which is 0x7f = 127, 0x7fff = 32,767 or 0x7ffffff = 8,388,607) in the case of overflow, and the smallest possible value (that is, the most-negative, which is -128, -32,-768 or -8,388,608 respectively) in the case of underflow. No log file message is generated.

Unsupported SQL Datatypes

RadAttr CST fields do not support SQL datatypes other than those discussed in this section (INTs of various sizes and sign, CHAR, VARCHAR, BINARY, and VARBINARY).

Unsupported datatypes include INT datatypes such as BIGINT, BIT, DECIMAL, TIME and DATE; CHAR datatypes such as TEXT; and BYTE datatypes such as BLOB.

Modified: 2017-10-26