Internet Engineering Task Force (IETF)                          A. DeKok
Request for Comments: 8044                                    FreeRADIUS
Updates: 2865, 3162, 4072, 6158, 6572, 7268                 January 2017
Category: Standards Track
ISSN: 2070-1721


                          Data Types in RADIUS

Abstract

   RADIUS specifications have used data types for two decades without
   defining them as managed entities.  During this time, RADIUS
   implementations have named the data types and have used them in
   attribute definitions.  This document updates the specifications to
   better follow established practice.  We do this by naming the data
   types defined in RFC 6158, which have been used since at least the
   publication of RFC 2865.  We provide an IANA registry for the data
   types and update the "RADIUS Attribute Types" registry to include a
   Data Type field for each attribute.  Finally, we recommend that
   authors of RADIUS specifications use these types in preference to
   existing practice.  This document updates RFCs 2865, 3162, 4072,
   6158, 6572, and 7268.

Status of This Memo

   This is an Internet Standards Track document.

   This document is a product of the Internet Engineering Task Force
   (IETF).  It represents the consensus of the IETF community.  It has
   received public review and has been approved for publication by the
   Internet Engineering Steering Group (IESG).  Further information on
   Internet Standards is available in Section 2 of RFC 7841.

   Information about the current status of this document, any errata,
   and how to provide feedback on it may be obtained at
   http://www.rfc-editor.org/info/rfc8044.

Copyright Notice

   Copyright (c) 2017 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents
   (http://trustee.ietf.org/license-info) in effect on the date of
   publication of this document.  Please review these documents
   carefully, as they describe your rights and restrictions with respect
   to this document.  Code Components extracted from this document must
   include Simplified BSD License text as described in Section 4.e of
   the Trust Legal Provisions and are provided without warranty as
   described in the Simplified BSD License.

Table of Contents

   1. Introduction ....................................................4
      1.1. Specification Problems with Data Types .....................4
      1.2. Implementation Problems with Data Types ....................5
      1.3. No Mandated Changes ........................................5
      1.4. Requirements Language ......................................5
   2. Use of Data Types ...............................................6
      2.1. Specification Use of Data Types ............................6
           2.1.1. Field Names for Attribute Values ....................6
           2.1.2. Attribute Definitions Using Data Types ..............7
           2.1.3. Format of Attribute Definitions .....................8
           2.1.4. Defining a New Data Type ............................9
      2.2. Implementation Use of Data Types ...........................9
   3. Data Type Definitions ..........................................10
      3.1. integer ...................................................12
      3.2. enum ......................................................12
      3.3. time ......................................................13
      3.4. text ......................................................14
      3.5. string ....................................................15
      3.6. concat ....................................................16
      3.7. ifid ......................................................17
      3.8. ipv4addr ..................................................18
      3.9. ipv6addr ..................................................18
      3.10. ipv6prefix ...............................................19
      3.11. ipv4prefix ...............................................20
      3.12. integer64 ................................................22
      3.13. tlv ......................................................23
      3.14. vsa ......................................................24
      3.15. extended .................................................26
      3.16. long-extended ............................................27
      3.17. evs ......................................................30
   4. Updated Registries .............................................31
      4.1. New "Data Type" Registry ..................................31
      4.2. Updates to the "RADIUS Attribute Types" Registry ..........32
   5. Security Considerations ........................................32
   6. IANA Considerations ............................................33
   7. References .....................................................33
      7.1. Normative References ......................................33
      7.2. Informative References ....................................34
   Acknowledgments ...................................................35
   Author's Address ..................................................35

1.  Introduction

   RADIUS specifications have historically defined attributes in terms
   of name, value, and data type.  Of these three pieces of information,
   the name is recorded by IANA in the "RADIUS Attribute Types" registry
   but is not otherwise managed or restricted, as discussed in
   [RFC6929], Section 2.7.1.  The value is managed by IANA and recorded
   in that registry.  The data type is not managed or recorded in the
   "RADIUS Attribute Types" registry.  Experience has shown that there
   is a need to create well-known data types and have them managed
   by IANA.

   This document defines an IANA RADIUS "Data Type" registry and updates
   the "RADIUS Attribute Types" registry to use those newly defined
   data types.  It recommends how both specifications and
   implementations should use the data types.  It extends the "RADIUS
   Attribute Types" registry to have a data type for each assigned
   attribute.

   In this section, we review the use of data types in specifications
   and implementations.  We highlight ambiguities and inconsistencies.
   The rest of this document is devoted to resolving those problems.

1.1.  Specification Problems with Data Types

   When attributes are defined in the specifications, the terms "Value"
   and "String" are used to refer to the contents of an attribute.
   However, these names are used recursively and inconsistently.  We
   suggest that defining a field to recursively contain itself is
   problematic.

   A number of data type names and definitions are given in
   [RFC2865], Section 5, at the bottom of page 25.  These data types are
   named and clearly defined.  However, this practice was not continued
   in later specifications.

   Specifically, [RFC2865] defines attributes of data type "address" to
   carry IPv4 addresses.  Despite this definition, [RFC3162] defines
   attributes of data type "Address" to carry IPv6 addresses.  We
   suggest that the use of the word "address" to refer to disparate
   data types is problematic.

   Other failures are that [RFC3162] does not give a data type name and
   definition for the data types IPv6 address, Interface-Id, or IPv6
   prefix.  [RFC2869] defines Event-Timestamp to carry a time but does
   not reuse the "time" data type defined in [RFC2865].  Instead, it
   just repeats the "time" definition.  [RFC6572] defines multiple
   attributes that carry IPv4 prefixes.  However, an "IPv4 prefix" data

   type is not named, defined as a data type, or called out as an
   addition to RADIUS.  Further, [RFC6572] does not follow the
   recommendations of [RFC6158] and does not explain why it fails to
   follow those recommendations.

   These ambiguities and inconsistencies need to be resolved.

1.2.  Implementation Problems with Data Types

   RADIUS implementations often use "dictionaries" to map attribute
   names to type values and define data types for each attribute.  The
   data types in the dictionaries are defined by each implementation but
   correspond to the "ad hoc" data types used in the specifications.

   In effect, implementations have seen the need for well-defined
   data types and have created them.  It is time for RADIUS
   specifications to follow this practice.

1.3.  No Mandated Changes

   This document mandates no changes to any past, present, or future
   RADIUS implementation.  It instead documents existing practice in
   order to simplify the process of writing RADIUS specifications,
   clarify the interpretation of RADIUS standards, and improve the
   communication between specification authors and IANA.

   This document suggests that implementations SHOULD use the data types
   defined here, in preference to any ad hoc data types currently in
   use.  This suggestion should have a minimal effect on
   implementations, as most ad hoc data types are compatible with the
   ones defined here.  Any difference will typically be limited to the
   name of the data type.

   This document updates [RFC6158] to permit the data types defined in
   the "Data Type" registry as "basic data types", as per Section 2.1 of
   [RFC6158].  The recommendations of [RFC6158] are otherwise unchanged.

1.4.  Requirements Language

   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in [RFC2119].

2.  Use of Data Types

   The data types can be used in two places: specifications and
   implementations.  This section discusses both uses and gives guidance
   on using the data types.

2.1.  Specification Use of Data Types

   In this section, we give recommendations for how specifications
   should be written using data types.  We first describe how attribute
   field names can be consistently named.  We then describe how
   attribute definitions should use the data types and deprecate the use
   of "ASCII art" for attribute definitions.  We suggest a format for
   new attribute definitions.  This format includes recommended fields
   and suggestions for how those fields should be described.

   Finally, we make recommendations for how new data types should be
   defined.

2.1.1.  Field Names for Attribute Values

   Previous specifications used inconsistent and conflicting names for
   the contents of RADIUS attributes.  For example, the term "Value" is
   used in [RFC2865], Section 5 to define a field that carries the
   contents of an attribute.  It is then used in later sections as the
   subfield of attribute contents.  The result is that the field is
   defined as recursively containing itself.  Similarly, "String" is
   used both as a data type and as a subfield of other data types.

   We correct this ambiguity by using context-specific names for various
   fields of attributes and data types.  It then becomes clear that, for
   example, a field called "VSA-Data" must contain different data than a
   field called "EVS-Data".  Each new name is defined where it is used.

   We also define the following term:

      Attr-Data

         The Value field of an Attribute as defined in
         [RFC2865], Section 5.  The contents of this field MUST be of a
         valid data type as defined in the RADIUS "Data Type" registry.

   We consistently use "Attr-Data" to refer to the contents of an
   attribute, instead of the more ambiguous name "Value".  It is
   RECOMMENDED that new specifications follow this practice.

   We consistently use "Value" to refer to the contents of a data type,
   where that data type is simple.  For example, an "integer" can have a
   "Value".  In contrast, a Vendor-Specific Attribute carries complex
   information and thus cannot have a "Value".

   For data types that carry complex information, we name the fields
   based on the data type.  For example, a Vendor-Specific Attribute is
   defined to carry a "vsa" data type, and the contents of that
   data type are described herein as "VSA-Data".

   These terms are used in preference to the term "String", which was
   previously used in ambiguous ways.  It is RECOMMENDED that future
   specifications use type-specific names and the same naming scheme for
   new types.  This use will maintain consistent definitions and help to
   avoid ambiguities.

2.1.2.  Attribute Definitions Using Data Types

   New RADIUS specifications MUST define attributes using data types
   from the RADIUS "Data Type" registry.  The specification may, of
   course, define a new data type, update the "Data Type" registry, and
   use the new data type, all in the same document.  The guidelines
   given in [RFC6929] MUST be followed when defining a new data type.

   Attributes can usually be completely described via the Attribute Type
   value, name, and data type.  The use of ASCII art is then limited
   only to the definition of new data types and for complex data types.

   Use of the new extended attributes [RFC6929] makes ASCII art even
   more problematic.  An attribute can be allocated from any of the
   extended spaces, with more than one option for the attribute header
   format.  This allocation decision is made after the specification has
   been accepted for publication.  As the allocation affects the format
   of the attribute header, it is essentially impossible to create the
   correct ASCII art prior to final publication.  Allocation from the
   different spaces also changes the value of the Length field, making
   it difficult to define it correctly prior to final publication of the
   document.

   It is therefore RECOMMENDED that ASCII art diagrams not be used for
   new RADIUS attribute specifications.

2.1.3.  Format of Attribute Definitions

   When defining a new attribute, the following fields SHOULD be given:

      Description

         A description of the meaning and interpretation of the
         attribute.

      Type

         The Attribute Type value, given in the "dotted number" notation
         from [RFC6929].  Specifications can often leave this as "TBD"
         (to be determined) and request that IANA fill in the allocated
         values.

      Length

         A description of the length of the attribute.  For attributes
         of variable length, a maximum length SHOULD be given.  Since
         the Length value may depend on the Type value, the definition
         of Length may be affected by IANA allocations.

      Data Type

         One of the named data types from the RADIUS "Data Type"
         registry.

      Value

         A description of any attribute-specific limitations on the
         values carried by the specified data type.  If there are no
         attribute-specific limitations, then the description of this
         field can be omitted, so long as the Description field is
         sufficiently explanatory.

         Where the values are limited to a subset of the possible range,
         valid range(s) MUST be defined.

         For attributes of data type "enum", a list of enumerated values
         and names MUST be given, as shown in [RFC2865], Section 5.6.

   Using a consistent format for attribute definitions helps to make the
   definitions clearer.

2.1.4.  Defining a New Data Type

   When a specification needs to define a new data type, it SHOULD
   follow the format used by the definitions in Section 3 of this
   document.  The text at the start of the data type definition MUST
   describe the data type, including the expected use, and why a new
   data type is required.  That text SHOULD include limits on expected
   values and why those limits exist.  The fields "Name", "Value",
   "Length", and "Format" MUST be given, along with values.

   The Name field SHOULD be a single name, all lowercase.

   Contractions such as "ipv4addr" are RECOMMENDED where they add
   clarity.

   We note that the use of "Value" in the RADIUS "Data Type" registry
   can be confusing.  That name is also used in attribute definitions,
   but with a different meaning.  We trust that the meaning here is
   clear from the context.

   The Value field SHOULD be given as "TBD" in specifications.  That
   number is assigned by IANA.

   The Format field SHOULD be defined with ASCII art in order to have a
   precise definition.  Machine-readable formats are also RECOMMENDED.

   The definition of a new data type should be done only when absolutely
   necessary.  We do not expect a need for a large number of new
   data types.  When defining a new data type, the guidelines of
   [RFC6929] with respect to data types MUST be followed.

   It is RECOMMENDED that vendors not define "vendor-specific"
   data types.  As discussed in [RFC6929], those data types are rarely
   necessary and can cause interoperability problems.

   Any new data type MUST have a unique name in the RADIUS "Data Type"
   registry.  The number of the data type will be assigned by IANA.

2.2.  Implementation Use of Data Types

   Implementations not supporting a particular data type MUST treat
   attributes of that data type as being of data type "string", as
   defined in Section 3.5.  It is RECOMMENDED that such attributes
   be treated as "invalid attributes", as defined in
   [RFC6929], Section 2.8.

   Where the contents of a data type do not match the definition,
   implementations MUST treat the enclosing attribute as being an
   invalid attribute.  This requirement includes, but is not limited to,
   the following situations:

   *  Attributes with values outside of the allowed range(s) for the
      data type, e.g., as given in the data types "integer", "ipv4addr",
      "ipv6addr", "ipv4prefix", "ipv6prefix", or "enum".

   *  "text" attributes where the contents do not match the required
      format.

   *  Attributes where the length is shorter or longer than the allowed
      length(s) for the given data type.

   The requirements for Reserved fields are more difficult to quantify.
   Implementations SHOULD be able to receive and process attributes
   where Reserved fields are non-zero.  We do not, however, define any
   "correct" processing of such attributes.  Instead, specifications
   that define one or more new meanings for Reserved fields SHOULD
   describe how each new meaning is compatible with older
   implementations.  We expect that such descriptions are derived from
   practical experience with implementations.  Implementations MUST set
   Reserved fields to zero when creating attributes.

3.  Data Type Definitions

   This section defines the new data types.  For each data type, it
   gives a definition, a name, a number, a length, and an encoding
   format.  Where relevant, it describes subfields contained within the
   data type.  These definitions have no impact on existing RADIUS
   implementations.  There is no requirement that implementations use
   these names.

   Where possible, the name of each data type has been taken from
   previous specifications.  In some cases, a different name has been
   chosen.  The change of name is sometimes required to avoid ambiguity
   (i.e., "address" versus "Address").  Otherwise, the new name has been
   chosen to be compatible with [RFC2865] or with usage in common
   implementations.  In some cases, new names are chosen to clarify the
   interpretation of the data type.

   The numbers assigned herein for the data types have no meaning other
   than to permit them to be tracked by IANA.  As RADIUS does not encode
   information about data types in a packet, the numbers assigned to a
   data type will never occur in a packet.  It is RECOMMENDED that new
   implementations use the names defined in this document in order to
   avoid confusion.  Existing implementations may choose to use the
   names defined here, but that is not required.

   The encoding of each data type is taken from previous specifications.
   The fields are transmitted from left to right.

   Where the data types have interdependencies, the simplest data type
   is given first, and dependent ones are given later.

   We do not create specific data types for the "tagged" attributes
   (i.e., attributes containing a Tag field) defined in [RFC2868].  That
   specification defines the tagged attributes as being backwards
   compatible with pre-existing data types.  In addition,
   [RFC6158], Section 2.1 says that tagged attributes should not be
   used.  There is therefore no benefit to defining additional
   data types for these attributes.  We trust that implementors will be
   aware that tagged attributes must be treated differently from
   non-tagged attributes of the same data type.

   Similarly, we do not create data types for some attributes having a
   complex structure, such as CHAP-Password, ARAP-Features, or
   Location-Information.  ("CHAP" refers to the Challenge Handshake
   Authentication Protocol, and "ARAP" refers to the Apple Remote Access
   Protocol.)  We need to strike a balance between correcting earlier
   mistakes and making this document more complex.  In some cases, it is
   better to treat complex attributes as being of type "string", even
   though they need to be interpreted by RADIUS implementations.  The
   guidelines given in Section 6.3 of [RFC6929] were used to make this
   determination.