Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 8044

Data Types in RADIUS

Pages: 35
Proposed Standard
Updates:  286531624072615865727268
Part 1 of 2 – Pages 1 to 11
None   None   Next

Top   ToC   RFC8044 - Page 1
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.
Top   ToC   RFC8044 - Page 2
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.
Top   ToC   RFC8044 - Page 3

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
Top   ToC   RFC8044 - Page 4

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
Top   ToC   RFC8044 - Page 5
   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].
Top   ToC   RFC8044 - Page 6

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.
Top   ToC   RFC8044 - Page 7
   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.
Top   ToC   RFC8044 - Page 8

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.
Top   ToC   RFC8044 - Page 9

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.
Top   ToC   RFC8044 - Page 10
   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.
Top   ToC   RFC8044 - Page 11
   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.


(next page on part 2)

Next Section