RFC 6158

RADIUS Design Guidelines

📅 published March 2011, from ietf

RFC 6158: RADIUS Design Guidelines 💖

Okay bestie, this is RFC 6158 🎀, and it's titled "RADIUS Design Guidelines." It's a Best Current Practice (BCP 158, ISSN 2070-1721) published in March 2011 ✨. The lead author is A. DeKok, Ed., from FreeRADIUS, and G. Weber is listed as an Individual Contributor 🫶. The title block doesn't say anything about obsoleting or updating other documents.

Abstract ✨

This doc gives guidelines for designing the attributes used by the Remote Authentication Dial In User Service (RADIUS) protocol 🧚. The authors hope it'll be useful for people writing and reviewing future RADIUS attribute specs, both at the IETF and at other Standards Development Organizations (SDOs) 💜.

Status of This Memo 📜

This memo documents an Internet Best Current Practice.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It went through public review and got approved for publication by the Internet Engineering Steering Group (IESG). More info on BCPs is in Section 2 of RFC 5741 🌸.

You can find out the current status of this document, any errata, and how to give feedback on it at http://www.rfc-editor.org/info/rfc6158 🦋.

Copyright (c) 2011 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) as they stand on the date this document was published. Please actually read these, because they lay out your rights and restrictions for this document 👀. Code Components pulled out of this document must include the Simplified BSD License text, as described in Section 4.e of the Trust Legal Provisions, and they come without warranty, as the Simplified BSD License describes 🔥.

This document may contain material from IETF Documents or IETF Contributions that were published or made publicly available before November 10, 2008 📚. The person(s) who control the copyright in some of that material may not have given the IETF Trust permission to allow modifications outside the IETF Standards Process. So unless you get an adequate license from whoever controls the copyright in those materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process 🙈. The only exceptions are formatting it for publication as an RFC or translating it into languages other than English 🌈.

Table of Contents 🧾

   1. Introduction ....................................................3
      1.1. Terminology ................................................4
      1.2. Requirements Language ......................................4
      1.3. Applicability ..............................................5
           1.3.1. Reviews .............................................5
   2. Guidelines ......................................................6
      2.1. Data Types .................................................8
      2.2. Vendor Space ...............................................9
      2.3. Service Definitions and RADIUS .............................9
      2.4. Translation of Vendor Specifications ......................10
   3. Rationale ......................................................11
      3.1. RADIUS Operational Model ..................................11
      3.2. Data Model Issues .........................................14
           3.2.1. Issues with Definitions of Types ...................15
           3.2.2. Tagging Mechanism ..................................16
           3.2.3. Complex Data Types .................................16
           3.2.4. Complex Data Type Exceptions .......................18
      3.3. Vendor Space ..............................................19
           3.3.1. Interoperability Considerations ....................20
           3.3.2. Vendor Allocations .................................20
           3.3.3. SDO Allocations ....................................20
      3.4. Polymorphic Attributes ....................................21
   4. IANA Considerations ............................................22
   5. Security Considerations ........................................22
      5.1. New Data Types and Complex Attributes .....................23
   6. References .....................................................24
      6.1. Normative References ......................................24
      6.2. Informative References ....................................24
   Appendix A.  Design Guidelines Checklist ..........................27
      A.1. Types Matching the RADIUS Data Model ......................27
         A.1.1. Transport of Basic Data Types ........................27
         A.1.2. Transport of Authentication and Security Data ........27
         A.1.3. Opaque Data Types ....................................27
         A.1.4. Pre-existing Data Types ..............................28

      A.2. Improper Data Types .......................................28
         A.2.1. Simple Data Types ....................................28
         A.2.2. More Complex Data Types ..............................29
      A.3. Vendor-Specific Formats ...................................29
      A.4. Changes to the RADIUS Operational Model ...................30
      A.5. Allocation of Attributes ..................................31
   Appendix B.  Complex Attributes ...................................32
      B.1. CHAP-Password .............................................32
      B.2. CHAP-Challenge ............................................32
      B.3. Tunnel-Password ...........................................33
      B.4. ARAP-Password .............................................33
      B.5. ARAP-Features .............................................34
      B.6. Connect-Info ..............................................34
      B.7. Framed-IPv6-Prefix ........................................35
      B.8. Egress-VLANID .............................................36
      B.9. Egress-VLAN-Name ..........................................37
      B.10. Digest-* .................................................37
   Acknowledgments ...................................................37

1. Introduction ✨

This doc gives guidelines for designing Remote Authentication Dial In User Service (RADIUS) attributes, both within the IETF and within other Standards Development Organizations (SDOs) 🌟. The big hope is that these guidelines encourage people to write and publish high-quality RADIUS attribute specs 💖.

But the advice here won't help anyone unless people actually use it 🙈. Just like "Guidelines for Authors and Reviewers of MIB Documents" [RFC4181], authors are expected to check their document against these guidelines before publishing it or asking for review (like an "Expert Review" described in [RFC3575]) 📝. Reviewers, like WG participants or the Authentication, Authorization, and Accounting (AAA) Doctors [DOCTORS], are also expected to use this document, which should make reviews more consistent 🫶.

To hit these goals, this doc has to cover the science of attribute design and also the art 🎨. So besides the most common issues, it explains some of the reasons behind the guidelines 💅. Those reasons include complexity trade-offs, which is why it's hard to write "hard and fast" rules for attribute design ⚖️. The doc works through those trade-offs by reviewing how current attributes are used 🔍.

Here's how the rest of the doc is laid out. Section 1 covers where the guidelines apply and describes a recommended review process for RADIUS specs 🗂️. Section 2 defines the design guidelines in terms of what is "RECOMMENDED" and "NOT RECOMMENDED" 🌸. Section 3 explains the rationale behind the guidelines from the previous section 🧠. Appendix A repeats the guidelines as a "checklist" 📋. Appendix B talks about previously defined attributes that don't follow the guidelines 👀.

New RADIUS spec authors can become compliant with the design guidelines by going through the checklists in Appendix A ✅. Reviewers of RADIUS specs are expected to know the entire document 🧚.

1.1. Terminology

This document uses the following terms:

Network Access Server (NAS) A device that gives a user access to a network 🌐.

RADIUS server A RADIUS authentication, authorization, and accounting (AAA) server is an entity that provides one or more AAA services to a NAS 🖥️.

Standard space Codes in the RADIUS Attribute Type Space that are allocated by IANA and that follow the format defined in Section 5 of RFC 2865 [RFC2865] 🎀.

Vendor space The contents of the Vendor-Specific Attribute (VSA), as defined in [RFC2865], Section 5.26. These attributes give each vendor (identified by the Vendor-Type field) its own attribute type space in the String field, which they can self-allocate 💜.

1.2. 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] 🔑.

1.3. Applicability ✨

Okay bestie, let's talk about who this advice is actually for 🎀 It covers RADIUS attributes that carry service-provisioning, authentication, or accounting data, using the attribute encodings and data formats from RFC 2865 [RFC2865], RFC 2866 [RFC2866], and subsequent RADIUS RFCs 💅

Since this doc is a Best Current Practice, it doesn't update or deprecate existing standards 🫶 So when it says "MUST" and "MUST NOT," it's only pointing at requirements that already live in older docs. No new drama, promise 🙈

It is RECOMMENDED that everyone follows these guidelines for all new RADIUS specs, whether they come from a vendor, an SDO, or the IETF 🔥 That's how you get the widest possible applicability and interoperability while needing minimal changes to existing systems ✨ Specs that want an allocation in the standard space are expected to follow these guidelines too, and if they can't, they should explain why not 🧚

Now, there are situations where vendors or SDOs can choose not to follow these guidelines without major consequences 👑 Section 5.26 of [RFC2865] literally says VSAs are "available to allow vendors to support their own extended Attributes not suitable for general usage" 💖 So for specs that are "not suitable for general usage," limited interoperability and not being able to use existing implementations may be acceptable, and in those cases, vendors and SDOs MAY choose not to conform to these guidelines 🦋

Note that the RADEXT WG is currently (as of 2011) working on updates to RADIUS 👀 Those updates will come with their own usage guidelines, which may modify some of the rules here, like defining new data types, practices, etc. 🌈

Last but not least: RADIUS protocol changes, or attribute specs (like Service-Type) that can, in effect, provide new RADIUS commands, need greater expertise and deeper review. The same goes for changes to the RADIUS operational model 😭 So those changes are outside the scope of this document and MUST NOT be undertaken outside the IETF. Not me saying no to freelancing 💀

1.3.1. Reviews 🔍

For specs using attributes in the standard space, conformance with the design guidelines in this document is expected unless a good case can be made for an exception 💅 Reviewers SHOULD use the design guidelines as a review checklist ✅

IETF review isn't required for specs using the vendor space, but it may still be super beneficial 🌸 Experience has shown that attributes not originally designed for general usage can later get wide-spread deployment. The Vendor-Specific Attributes defined in [RFC2548] are a perfect example, since they've been widely implemented within IEEE 802.11 Access Points 📡

If you want help writing a spec that follows these guidelines, authors can request review by emailing the AAA Doctors [DOCTORS] or an equivalent mailing list ✉️ The IETF Operations & Management Area Directors will then arrange for the review to be completed and posted to the AAA Doctors mailing list [DOCTORS], the RADEXT WG mailing list, or other IETF mailing lists. Reviews are handled by volunteers, so responses are best-effort with no service-level guarantees, so be patient, babe 🫶 Authors are encouraged to seek review as early as possible to avoid potential delays ⏰

Reviewers need access to the spec, so vendors and SDOs are encouraged to make it publicly available 🌍 If the RADIUS spec is embedded in a bigger document that can't be made public, the RADIUS attribute and value definitions can be put on a public web site or published as an Informational RFC, as with [RFC4679] 📄

The review process requires neither an allocation of attributes in the standard space nor publication of an RFC 🙅‍♀️ Making SDOs or vendors rehost VSAs into the standard space just to get a review would put pressure on the standard space. It may also be harmful to interoperability, since it would create two ways to provision the same service 😤 Rehosting may even require changes to the RADIUS data model, which would affect implementations that don't plan to support the SDO or vendor specs.

Similarly, vendors are encouraged to make their specs publicly available for maximum interoperability 🦋 That said, a vendor doesn't have to request publication of a VSA spec as an RFC 💖

2. Guidelines 📚

The RADIUS protocol, as defined in [RFC2865] and [RFC2866], uses elements called attributes to represent authentication, authorization, and accounting data 🎀

Unlike Simple Network Management Protocol (SNMP), first defined in [RFC1157] and [RFC1155], RADIUS doesn't have a formal data definition language 🙃 The data type of a RADIUS attribute isn't sent on the wire. Instead, it's fixed when the attribute is defined. Based on the RADIUS attribute type code, RADIUS clients and servers can figure out the data type from pre-configured entries in a data dictionary 📖

To explain what this early RADIUS design decision means, we split data types into two kinds: "basic" and "complex" 🧩 Basic data types use one of the existing RADIUS data types from Section 2.1, wrapped in a [RFC2865] RADIUS attribute or a [RFC2865] RADIUS VSA. Everything else is a "complex type" 💜

RADIUS attributes fall into one of three broad categories:

  • Attributes that matter to a single vendor, e.g., for a product or product line. Minimal cross-vendor interoperability is needed. Vendor-Specific Attributes (VSAs) are the right call here. Code-point allocation is managed by the vendor, within the vendor space defined by their Private Enterprise Number (PEN), as given in the Vendor-Id field 🏷️
  • Attributes that matter to an industry segment, where an SDO defines the attributes for that industry. Multi-vendor interoperability within the segment is expected. Vendor-Specific Attributes (VSAs) MUST be used. Code-point allocation is managed by the SDO, within the vendor space defined by the SDO's PEN rather than an individual vendor's PEN 🤝
  • Attributes that are of broad interest to the Internet community. Multi-vendor interoperability is expected. Attributes in the standard space are the right fit for this and are allocated via IANA as described in [RFC3575]. The standard space is a finite resource and the only attribute space available for use by IETF working groups, vendors, and SDOs, so vendors and SDOs are encouraged to use the vendor space instead of requesting standard-space allocations 🌱 Using attribute type codes reserved for standard attributes is considered antisocial behavior and is strongly discouraged 🙅‍♀️

2.1. Data Types 🍓

RADIUS defines a limited set of data types, called "basic data types." The following data qualifies as "basic data types":

  • 32-bit unsigned integer in network byte order.
  • Enumerated data types, represented as a 32-bit unsigned integer with a list of name-to-value mappings (e.g., Service-Type).
  • IPv4 address in network byte order.
  • Time as a 32-bit unsigned value in network byte order, in seconds since 00:00:00 UTC, January 1, 1970.
  • IPv6 address in network byte order.
  • Interface-Id (8-octet string in network byte order).
  • IPv6 prefix.
  • String (i.e., binary data), totaling 253 octets or less in length. This includes the opaque encapsulation of data structures defined outside of RADIUS. See also Appendix A.1.3 for additional discussion.
  • UTF-8 text [RFC3629], totaling 253 octets or less in length.

Note that the length limits for VSAs of type String and Text are less than 253 octets, due to the extra overhead of the Vendor-Specific encoding ⚠️

The following data also qualifies as "basic data types":

  • Attributes grouped into a logical container using the [RFC2868] tagging mechanism. This approach is NOT RECOMMENDED (see Section 3.2.2), but it's permissible where the alternatives are worse 😬
  • Attributes that need to transport more than 253 octets of Text or String data. This includes the opaque encapsulation of data structures defined outside of RADIUS, e.g., EAP-Message.

All other data formats (including nested attributes) are "complex data types" and are NOT RECOMMENDED for normal use 🙈 Complex data types MAY be used where they reduce complexity in non-RADIUS systems, or where basic data types would be awkward (such as where grouping is required to link related attributes). There are no "hard and fast" rules for where complexity is best located, so each situation gets decided case by case 🧠 Examples of this trade-off are discussed in Appendix B. Where a complex data type is selected, an explanation SHOULD be offered as to why it was necessary 📝

2.2. Vendor Space 🌷

The vendor space is the contents of the Vendor-Specific Attribute ([RFC2865], Section 5.26) where the Vendor-Id defines the space for a particular vendor, and the contents of the "String" field define a unique attribute type space for that vendor. As discussed there, it's meant for vendors and SDOs to support their own attributes that aren't suitable for general use 💖

The encoding of attributes within the vendor space is under the control of vendors and SDOs, but following these guidelines is advantageous, since it enables maximum interoperability with minimal changes to existing systems 🫶

For example, RADIUS server support for new attributes using "basic data types" can typically be done by editing a RADIUS dictionary. "Complex data types," on the other hand, typically require RADIUS server code changes, which can add complexity and delays to implementation 🐢

Vendor RADIUS Attribute specifications SHOULD self-allocate attributes from the vendor space rather than request an allocation from the standard space 🎯

VSA encodings that don't follow the [RFC2865], Section 5.26 encoding scheme are NOT RECOMMENDED. [RFC2865] doesn't mandate it, but implementations commonly assume the Vendor Id can be used as a key to determine the on-the-wire encoding of a VSA 👀 So vendors SHOULD NOT use multiple encodings for VSAs associated with a particular Vendor Id. A vendor that wants to use multiple VSA encodings SHOULD request one Vendor Id for each VSA encoding it will use 🌈

2.3. Service Definitions and RADIUS ✨

okay so RADIUS specs explain how an existing service or protocol can get provisioned using RADIUS, usually through the Service-Type Attribute 💅 That means a RADIUS attribute spec is expected to reference the docs that define the protocol or service being provisioned. Within the IETF, a RADIUS attribute spec SHOULD NOT be used to define the protocol or service being provisioned. New services that use RADIUS for provisioning SHOULD be defined elsewhere and then referenced in the RADIUS spec 🫶

New attributes, or new values of existing attributes, SHOULD NOT be used to define new RADIUS commands. RADIUS attributes are meant to:

  • authenticate users
  • authorize users (i.e., service provisioning or changes to provisioning)
  • account for user activity (i.e., logging of session activity)

The rules for getting new commands (that's the Code field in the packet header) and new attributes in the standard space are described in [RFC3575], Section 2.1 📚🌸

2.4. Translation of Vendor Specifications

okay this part is so important 🙈 [RFC2865], Section 5.26 defines Vendor-Specific Attributes like this:

This Attribute is available to allow vendors to support their own extended Attributes not suitable for general usage. It MUST NOT affect the operation of the RADIUS protocol. Servers not equipped to interpret the vendor-specific information sent by a client MUST ignore it (although it may be reported). Clients which do not receive desired vendor-specific information SHOULD make an attempt to operate without it, although they may do so (and report they are doing so) in a degraded mode.

So the limit on changes to the RADIUS protocol basically stops VSAs from changing the big stuff about how RADIUS works, like messing with RADIUS packet sequences or adding new commands 🚫 The "must work without VSAs" rule has turned out to be less of a blocker than you'd think, though, because a RADIUS client and server can totally agree they both support VSAs, and then reset their expectations from there ✨

So [RFC2865] gives vendors a LOT of room to build new attributes in the vendor space, while still blocking protocol variants 💅 That flexibility means RADIUS attributes can often be built in the vendor space with no loss in functionality (and maybe even a gain) 🦋

Here's the thing: moving vendor-space attributes into the standard space might only give modest benefits, and it speeds up using up the standard space 😭 Not every RADIUS attribute spec that needs interoperability will come from the IETF and get allocated from the standard space, and that's fine. The more scalable move is to lean into the flexibility of the vendor space while working on the quality and availability of RADIUS attribute specs, wherever they're developed 🌈

It is therefore NOT RECOMMENDED that specs meant only for a vendor or SDO get translated into the standard space 💀

3. Rationale ✨

this section explains the reasoning behind the recommendations above 🧚

3.1. RADIUS Operational Model

The RADIUS operational model has a few assumptions baked in:

  • The RADIUS protocol is stateless.
  • Provisioning of services is not possible within an Access-Reject or Disconnect-Request.
  • There is a distinction between authorization checks and user authentication.
  • The protocol provides for authentication and integrity protection of packets.
  • The RADIUS protocol is a Request/Response protocol.
  • The protocol defines packet length restrictions.

Now, RADIUS servers can keep state, but the RADIUS protocol itself is stateless. Info can still get passed from one protocol transaction to another through the State Attribute 🔁 So documents that need stateful behavior without using the State Attribute are inherently incompatible with RADIUS as defined in [RFC2865] and MUST be redesigned 🚨 For more on the State Attribute, check out [RFC5080], Section 2.1.1 🔍

As noted in [RFC5080], Section 2.6, an Access-Reject is meant to deny access to the requested service. So RADIUS doesn't allow provisioning services within an Access-Reject or Disconnect-Request 🙅‍♀️ Documents that include provisioning of services in either of those are inherently incompatible with RADIUS and need to be redesigned.

[RFC5176], Section 3 says this:

A Disconnect-Request MUST contain only NAS and session identification attributes. If other attributes are included in a Disconnect-Request, implementations MUST send a Disconnect-NAK; an Error-Cause Attribute with value "Unsupported Attribute" MAY be included.

So documents that include provisioning of services within a Disconnect-Request are inherently incompatible with RADIUS too, and need a redesign 💅

As noted in [RFC5080], Section 2.1.1, a RADIUS Access-Request may NOT contain user authentication attributes or a State Attribute that links it to an earlier user authentication. That kind of Access-Request is called an authorization check, and it gives no assurance it's tied to a live user 👀 RADIUS specs that define attributes with confidential info (like Tunnel-Password) should be careful to stop those attributes from being sent back in response to an authorization check. [RFC5080], Section 2.1.1 also notes that authentication mechanisms need to tie a sequence of Access-Request/Access-Challenge packets together into one authentication session. The State Attribute is RECOMMENDED for this 🔐

[RFC2865] didn't require authentication and integrity protection for RADIUS Access-Request packets, but later auth mechanism specs, like RADIUS/EAP [RFC3579] and Digest Authentication [RFC5090], did require it for certain RADIUS packets 🙌 [RFC5080], Section 2.1.1 makes this RECOMMENDED for all Access-Request packets, including the ones doing authorization checks. And we expect new RADIUS auth mechanism specs to keep doing this too ✨

The RADIUS protocol defined in [RFC2865] is a request-response protocol between RADIUS clients and servers. A single RADIUS request packet ([RFC2865], [RFC2866], or [RFC5176]) will get at most a single response packet in return, sent to the IP address and port of the RADIUS client that sent the request 📬 Changing this model would likely need major revisions to existing implementations, so this practice is NOT RECOMMENDED 🙅‍♀️

The Length field in the RADIUS packet header is defined in [RFC2865] Section 3. It says the maximum length of a RADIUS packet is 4096 octets. So attribute designers SHOULD NOT assume a RADIUS implementation can successfully process RADIUS packets bigger than 4096 octets 🫠

Even when packets are under 4096 octets, they can still be bigger than the Path Maximum Transmission Unit (PMTU) 😬 Any packet bigger than the PMTU gets fragmented, which makes communications more brittle, since firewalls and filtering devices often discard fragments. Transport of fragmented UDP packets seems to be a poorly tested code path on network devices, and some devices seem unable to transport fragmented UDP packets at all, which makes it hard to deploy RADIUS in a network full of them 🥲 We RECOMMEND that RADIUS messages be kept as small as possible 🍓

If there's a situation where authentication, authorization, or accounting data might need to go in a packet bigger than 4096 octets, then one of these approaches is RECOMMENDED 🎀

  1. Utilization of a sequence of packets. For RADIUS authentication, a sequence of Access-Request/Access-Challenge packets would be used. For this to be feasible, attribute designers need to enable including attributes that can eat up a lot of space within Access-Challenge packets. To keep compatibility with existing NASes, either Access-Challenge packets need to be allowed (as with RADIUS/EAP, defined in [RFC3579]), or the NAS needs to indicate it supports receiving an Access-Challenge (as in RADIUS Location [RFC5580]). Also, the spec needs to clearly describe how attribute splitting gets signaled and how attributes in the sequence should be interpreted, without requiring stateful operation. Honestly, previous specs haven't always had the foresight they needed 😅 For example, even though very large filter rules are totally conceivable, the NAS-Filter-Rule Attribute defined in [RFC4849] is not permitted in an Access-Challenge packet, and no mechanism is specified for splitting a set of NAS-Filter-Rule Attributes across an Access-Request/Access-Challenge sequence 💀

For RADIUS accounting, moving large amounts of data would need a sequence of Accounting-Request packets. That's a non-trivial change to RADIUS, since RADIUS accounting clients would need to be modified to split the attribute stream across multiple Accounting-Requests, and billing servers would need to be modified to reassemble and interpret the attribute stream 🧩

  1. Utilization of names rather than values. If an attribute relates to a policy that could reasonably be pre-provisioned on the NAS, then the name of the pre-provisioned policy can be sent in an attribute instead of the policy itself, which could be quite large 🌟 An example is the Filter-Id Attribute defined in [RFC2865], Section 5.11, which lets a set of pre-provisioned filter rules be referenced by name 🦋
  2. Utilization of Packetization Layer Path MTU Discovery techniques, as specified in [RFC4821]. As a last resort, where the above techniques can't be made to work, it may be possible to apply the techniques described in [RFC4821] to discover the maximum supported RADIUS packet size on the path between a RADIUS client and a home server 🔎 This approach can avoid the complexity of using a sequence of packets, but dynamic discovery is likely to be time consuming and can't be guaranteed to work with existing RADIUS implementations. So this technique is not generally applicable 🥀

3.2. Data Model Issues 🎀

okay so [RFC2865], Section 5 defines the basic data types, but later specs didn't follow that practice 💅 Implementations then made up their own names for data types, so you end up with non-standard names for the same things 🙈

It gets messier too. The number of vendors and SDOs creating new attributes in the vendor space has exploded, and that has caused some divergence in how people design RADIUS attributes 😭 Different groups have evolved the data model to support things like new data types, attribute grouping, and attribute fragmentation, and each group has its own approach. These approaches are often incompatible, which adds complexity to RADIUS implementations 💀

So to avoid repeating old mistakes, this section walks through the history of the RADIUS data model and tries to write down what people are actually doing ✨

3.2.1. Issues with Definitions of Types 🧚

[RFC2865], Section 5 explicitly defines five data types: text, string, address, integer, and time. Both the names and the interpretations of the types are given 💖

Later RADIUS specs defined attributes using type names that [RFC2865] never defined, and they didn't define those new names the way [RFC2865] did. They also didn't consistently show the format of the value field using the same conventions as [RFC2865]. The result? The data type is ambiguous in some cases and may not be consistent across implementations. Not it 🙅‍♀️

It's out of scope for this document to fix every ambiguity in the existing RADIUS specs. But to prevent future ambiguities, it is RECOMMENDED that future RADIUS attribute specifications explicitly define newly created data types at the beginning of the document and clearly indicate the data type to be used for each attribute 🌸

For example, [RFC3162] uses, but doesn't explicitly define, a type that encapsulates an IPv6 address (Sections 2.1 and 2.4), and another type that encapsulates an IPv6 prefix (Section 2.3). The IPv6 address attributes are confusingly referred to as type "Address" in the document, which is a similar name to the "address" type defined in [RFC2865]. That one was defined to refer solely to IPv4 addresses. Confusing, bestie 😭

Also, the Framed-Interface-Id Attribute defined in [RFC3162], Section 2.2 has a value field of 8 octets, but its data type isn't explicitly indicated. So there's controversy over whether it was meant to be an 8-octet String or whether a special Interface-Id type was intended 🤔

Since attributes encapsulating an IPv6 address and an IPv6 prefix are already in use, it is RECOMMENDED that RADIUS server implementations support these as basic types, in addition to the types defined in [RFC2865]. When the intent is to represent a specific IPv6 address, an "IPv6 address" type SHOULD be used. It is possible to use an "IPv6 Prefix" type with a prefix length of 128 to represent an IPv6 address, but this usage is NOT RECOMMENDED. 🙅‍♀️ Implementations that support the Framed-Interface-Id Attribute may select a data type of their choosing (most likely an 8-octet String or a special "Interface Id" data type) 🦋

It's also worth noting that since RADIUS only supports unsigned integers of 32 bits, attributes using signed integer types or unsigned integer types of other sizes will require code changes and SHOULD be avoided 🔥

For [RFC2865] RADIUS VSAs, the length limit for the String and Text types is 247 octets instead of 253 octets, because the Vendor-Specific Attribute adds its own overhead 💅

3.2.2. Tagging Mechanism 🏷️

[RFC2868] defines an attribute grouping mechanism based on a one-octet tag value. Tunnel attributes that refer to the same tunnel are grouped together by using the same tag value 🌈

This tagging mechanism has some drawbacks, ngl. There are only a limited number of unique tags (31). The tags also aren't well suited for arbitrary binary data values, because it isn't always possible to tell whether the first byte after the Length is the tag or the first byte of the untagged value (assuming the tag is optional) 😵‍💫

Other limitations: when integer values are tagged, the value portion shrinks to three bytes, so only 24-bit numbers can be represented. The tagging mechanism also doesn't let you create nested groups of attributes. Some RADIUS implementations treat tagged attributes as having the additional data types tagged-string and tagged-integer, which makes implementing and managing RADIUS systems even more complicated 🥴

So for these reasons, the tagging scheme described in RFC 2868 is NOT RECOMMENDED for use as a generic grouping mechanism 🙈

3.2.3. Complex Data Types 🧩

Creating complex types can cause interoperability and deployment issues, so they need to be introduced with care. For example, the RADIUS attribute encoding is summarized in [RFC2865]:

    0                   1                   2
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
   |     Type      |    Length     |  Value ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

Some standard attributes pack multiple sub-fields into the "Value" field, which creates a non-standard (aka complex) type. Splitting those sub-fields into separate attributes, each with its own type and length, would have these benefits:

  • When manual data entry is required, it's easier for an administrator to enter the data as well-known types rather than as complex structures.
  • It enables additional error checking by leveraging the parsing and validation routines for well-known types.
  • It simplifies implementations by eliminating special-case, attribute-specific parsing.

One of the fundamental goals of the RADIUS protocol design was to let RADIUS servers be configured to support new attributes without requiring server code changes. RADIUS server implementations typically support basic data types and define attributes in a data dictionary. This architecture means a new attribute can be supported just by adding a dictionary entry, with no other RADIUS server code changes 📖

Code changes can still be needed in policy management systems and in the RADIUS server's receive path. That's because RADIUS server policy languages usually only allow limited operations (like comparisons or arithmetic) on the existing data types. Lots of existing RADIUS policy languages can't parse sub-elements or do more sophisticated matching 🫠

On the RADIUS client, code changes are typically required to implement a new attribute. The client usually has to compose the attribute dynamically when sending it. When receiving, a client needs to be able to parse the attribute and carry out the requested service. So clients need a detailed understanding of the new attribute, and data dictionaries are less useful on clients than on servers 🤓

Given all this, introducing new types can require code changes on the RADIUS server, which wouldn't be necessary if basic data types had been used instead. On top of that, if "ad hoc" types are used, attribute-specific parsing is required, which means more complex software to develop and maintain. More complexity can lead to more error-prone implementations, interoperability problems, and even security vulnerabilities 🚨 These issues can increase costs for network administrators, reduce reliability, and create deployment barriers 💜

3.2.4. Complex Data Type Exceptions 🌟

As described in Section 2.1, introducing complex data types is discouraged wherever viable alternatives exist. A possible exception is attributes that inherently require code changes on both the client and the server. For example, as described in Appendix B, complex attributes have been used for authentication and security attributes, which need to be dynamically computed and verified. Supporting this requires code changes on both the RADIUS client and server, no matter the attribute format. So in most cases, using complex attributes for these methods is acceptable and doesn't create additional interoperability or deployment issues 🫶

Another exception to the recommendation against complex types is types that the RADIUS server can treat as opaque data. For example, the EAP-Message Attribute, defined in [RFC3579], Section 3.1, contains a complex data type that is an Extensible Authentication Protocol (EAP) packet. Since the RADIUS server doesn't need to parse these complex types, the issues arising from server limitations don't come up. Similarly, since attributes of these complex types can be configured on the server using a data type of String, dictionary limitations aren't encountered either. Appendix A.1 includes a series of checklists that may be used to analyze a design for RECOMMENDED and NOT RECOMMENDED behavior in relation to complex types 📋

If the RADIUS Server simply passes the contents of an attribute on to some non-RADIUS part of the network, then the data is opaque to RADIUS and SHOULD be defined to be of type String. A concrete way to judge this is whether the attribute definition in the RADIUS document contains delineated fields for sub-parts of the data. If those fields need to be delineated in RADIUS, then the data is not opaque to RADIUS, and it SHOULD be separated into individual RADIUS attributes 🍓

An examination of existing RADIUS RFCs turns up a number of complex attributes that have already been defined. Appendix B lists the complex attributes used within [RFC2865], [RFC2868], [RFC2869], [RFC3162], [RFC4818], and [RFC4675]. The discussion of these attributes includes reasons why a complex type is acceptable, or suggestions for how the attribute could have been defined to follow the RADIUS data model 👑

In other cases, the data in the complex type is described in text within a specification. That works because the data types aren't sent within the attributes. They're a matter for endpoint interpretation. An implementation can define additional data types and use them today by matching them to the attribute's textual definition ✨

3.3. Vendor Space 🎀

Okay so the usage model for RADIUS VSAs is explained in [RFC2865], Section 6.2, and it basically says:

Note that RADIUS defines a mechanism for Vendor-Specific extensions (Attribute 26) and the use of that should be encouraged instead of allocation of global attribute types, for functions specific only to one vendor's implementation of RADIUS, where no interoperability is deemed useful.

Nevertheless, tons of new attributes have been defined in the vendor space anyway, especially where interoperability is not only useful but required 💅. SDOs outside the IETF, like IEEE 802 and the 3rd Generation Partnership Project (3GPP), have been assigned Vendor-Ids. That means they can define their own VSA encoding and assign Vendor types inside their own vendor space, as defined by their unique Vendor-Id 🦋.

Why is this getting so popular? Two big reasons:

  • Efficiency ⏩: Just like SNMP has an "Enterprise" Object Identifier (OID) space that works for vendors and other SDOs too, defining Vendor-Specific Attributes has become super common as part of standards work outside the IETF. For efficiency, it's easiest if the RADIUS attributes needed to manage a standard get developed in the same SDO that develops the standard itself. As noted in "Transferring MIB Work from IETF Bridge MIB WG to IEEE 802.1 WG" [RFC4663], today few vendors are willing to simultaneously fund people to take part in an SDO to complete a standard and also take part in the IETF to complete the associated RADIUS attributes specification 😭.
  • Attribute scarcity 🥲: The standard space is limited to 255 unique attributes, and only about half of them are still available for allocation. In the vendor space, the number of attributes available depends on how the attribute is encoded (the size of the Vendor type field).

3.3.1. Interoperability Considerations

Quick reminder for vendors and SDOs 🫶: the standard space and the enumerated value space for enumerated attributes are reserved for allocation through work published via the IETF, as noted in [RFC3575], Section 2.1. Some vendors and SDOs have given vendor-specific meaning to "unused" values from the standard space. Honestly? That causes interoperability issues and is counterproductive 🙈. Similarly, the vendor-specific enumeration practice discussed in [RFC2882], Section 2.2.1 is NOT RECOMMENDED.

If it's not possible to follow the IETF process, vendors and SDOs SHOULD self-allocate an attribute. That attribute MUST be in their own vendor space as defined by their unique Vendor-Id, as discussed in Sections 3.3.2 and 3.3.3 ✨.

The design and specification of VSAs for multi-vendor usage SHOULD get the same level of care as standard RADIUS attributes. Specifically, the provisions of this document that apply to standard RADIUS attributes also apply to VSAs for multi-vendor usage. No skipping the homework, bestie 📚.

3.3.2. Vendor Allocations

As noted in [RFC3575], Section 2.1, vendors are encouraged to use VSAs to define functions:

"specific only to one vendor's implementation of RADIUS, where no interoperability is deemed useful. For functions specific only to one vendor's implementation of RADIUS, the use of that should be encouraged instead of the allocation of global attribute types".

Why do vendors do this? It's a recognition that vendors want to keep change control over their own RADIUS specifications 👑. That control comes from requesting a PEN from the Internet Assigned Number Authority (IANA) to use as a Vendor-Id within a Vendor-Specific Attribute. After that, the vendor can allocate attributes within the vendor space defined by that Vendor-Id at their sole discretion. The same goes for data types, complex or otherwise: using them inside that vendor space is solely up to the vendor 💖.

3.3.3. SDO Allocations

Given how much RADIUS is being used now, it's become pretty clear that making SDOs do all their RADIUS work inside the IETF is inherently inefficient and unscalable 😩. So it is RECOMMENDED that SDO RADIUS Attribute specifications allocate attributes from the vendor space, rather than requesting an allocation from the RADIUS standard space, for attributes matching any of the following criteria:

  • Attributes relying on data types not defined within RADIUS
  • Attributes intended primarily for use within an SDO
  • Attributes intended primarily for use within a group of SDOs

Any new RADIUS attributes or values meant for interoperable use across a broad spectrum of the Internet community SHOULD follow the allocation process defined in [RFC3575] 🌸.

Same energy as the vendor section: this recommendation is a recognition that SDOs want to keep change control over their own RADIUS specifications. That change control can be obtained by requesting a PEN from the Internet Assigned Number Authority (IANA) for use as a Vendor-Id within a Vendor-Specific Attribute. The SDO can then allocate attributes within the vendor space defined by that Vendor-Id at their sole discretion. Likewise, the use of data types (complex or otherwise) inside that vendor space is solely under the SDO's discretion 🧚.

3.4. Polymorphic Attributes 🦄

A polymorphic attribute is one whose format or meaning is dynamic. For example, instead of a fixed data format, an attribute's format might change based on the contents of another attribute. Or the meaning of an attribute might depend on earlier packets in a sequence. Wild, right? 🤯

RADIUS server dictionary entries are usually static, which lets the user enter the contents of an attribute without any support for changing the format based on dynamic conditions. But this limit on static types doesn't stop implementations from running policies that return different attributes based on the contents of received attributes. That's a common feature of existing RADIUS implementations, so it's totally a thing ✨.

In general, polymorphism is NOT RECOMMENDED. Polymorphism rarely enables capabilities that couldn't be had by using multiple attributes. It also requires code changes in the RADIUS server in situations where attributes with fixed formats wouldn't need any. So polymorphism adds complexity while reducing generality, and it doesn't bring any matching benefits. Not it 🙅‍♀️.

Note that changing an attribute's format dynamically is not the same thing as using a fixed format and computing the attribute itself dynamically. RADIUS authentication attributes, such as User-Password, EAP-Message, etc., are computed dynamically but still use a fixed format. Totally different vibes 💅.

4. IANA Considerations 🌈

Good news: this document has no action items for IANA 🎉. It does, however, provide guidelines for Expert Reviewers appointed as described in [RFC3575] 🫶.

5. Security Considerations 🔥

Serious moment, bestie 💀. This specification provides guidelines for the design of RADIUS attributes used in authentication, authorization, and accounting. Threats and security issues for this application are described in [RFC3579] and [RFC3580], and security issues encountered in roaming are described in [RFC2607].

Obfuscation of RADIUS attributes on a per-attribute basis is necessary in some cases. The current standard mechanism for this is described in [RFC2865], Section 5.2 (for obscuring User-Password values), and it's based on the MD5 algorithm specified in [RFC1321]. MD5 and SHA-1 have recently become a huge focus of scrutiny and concern in security circles 😬, so using these algorithms in new attributes is NOT RECOMMENDED. Also, previous documents called this method generating "encrypted" data. That terminology is no longer accepted within the cryptographic community, so we're retiring it 🙈.

Where new RADIUS attributes use cryptographic algorithms, algorithm negotiation SHOULD be supported. Specification of a mandatory-to-implement algorithm is REQUIRED, and it is RECOMMENDED that the mandatory-to-implement algorithm be certifiable under FIPS 140 [FIPS] 🔐.

Where new RADIUS attributes encapsulate complex data types, or transport opaque data, the security considerations discussed in Section 5.1 SHOULD be addressed 🚨.

Message authentication in RADIUS is provided largely via the Message-Authenticator attribute. See Section 3.2 of [RFC3579] and also Section 2.2.2 of [RFC5080], which say that client implementations SHOULD include a Message-Authenticator Attribute in every Access-Request 💖.

In general, the security of the RADIUS protocol is poor 😭. Robust deployments SHOULD support a secure communications protocol such as IPsec. See Section 4 of [RFC3579] and Section 5 of [RFC3580] for a more in-depth explanation of these issues 📖.

Implementations that don't follow the suggestions in this document may be subject to problems such as ambiguous protocol decoding, packet loss leading to loss of billing information, and denial-of-service attacks. Yikes 💀.

5.1. New Data Types and Complex Attributes 🧨

The introduction of complex data types brings the potential for new security vulnerabilities. Experience shows that the common data types have few security vulnerabilities, or else that all known issues have been found and fixed 👀. New data types need new code, though, and new code may introduce new bugs and therefore new attack vectors.

Some systems let complex attributes be defined via a method that's more capable than traditional RADIUS dictionaries. These systems can reduce the security threat of new types significantly, but they don't remove it entirely 🛡️.

RADIUS servers are highly valued targets, since they control network access and interact with databases that store usernames and passwords 🎯. An extreme outcome of a vulnerability due to a new, complex type would be that an attacker is capable of taking complete control over the RADIUS server. Scary stuff 😱.

Using attributes that represent opaque data doesn't reduce this threat. The threat just moves from the RADIUS server to the system that consumes that opaque data. It's especially severe when the opaque data originates from the user and isn't validated by the NAS. In those cases, the RADIUS server is potentially exposed to attack by malware residing on an unauthenticated host 🦠.

Any system consuming opaque data that originates from a RADIUS system SHOULD be properly isolated from that RADIUS system and SHOULD run with minimal privileges. That way, any potential vulnerabilities in the non-RADIUS system will have minimal impact on the security of the system as a whole 🏰.

6. References 📚

6.1. Normative References

  • [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.
  • [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson, "Remote Authentication Dial In User Service (RADIUS)", RFC 2865, June 2000.
  • [RFC3575] Aboba, B., "IANA Considerations for RADIUS (Remote Authentication Dial In User Service)", RFC 3575, July 2003.

6.2. Informative References 📚

okay bestie, these are the extra reads that give the whole spec its backstory 🧚 (not required, just super useful), and every single one is listed below exactly as it's written 🫶

   [RFC1155]     Rose, M. and K. McCloghrie, "Structure and
                 identification of management information for TCP/IP-
                 based internets", STD 16, RFC 1155, May 1990.

   [RFC1157]     Case, J., Fedor, M., Schoffstall, M., and J. Davin,
                 "Simple Network Management Protocol (SNMP)", RFC 1157,
                 May 1990.

   [RFC1321]     Rivest, R., "The MD5 Message-Digest Algorithm", RFC
                 1321, April 1992.

   [RFC2548]     Zorn, G., "Microsoft Vendor-specific RADIUS
                 Attributes", RFC 2548, March 1999.

   [RFC2607]     Aboba, B. and J. Vollbrecht, "Proxy Chaining and Policy
                 Implementation in Roaming", RFC 2607, June 1999.

   [RFC2866]     Rigney, C., "RADIUS Accounting", RFC 2866, June 2000.

   [RFC2868]     Zorn, G., Leifer, D., Rubens, A., Shriver, J.,
                 Holdrege, M., and I. Goyret, "RADIUS Attributes for
                 Tunnel Protocol Support", RFC 2868, June 2000.

   [RFC2869]     Rigney, C., Willats, W., and P. Calhoun, "RADIUS
                 Extensions", RFC 2869, June 2000.

   [RFC2882]     Mitton, D., "Network Access Servers Requirements:
                 Extended RADIUS Practices", RFC 2882, July 2000.

   [RFC3162]     Aboba, B., Zorn, G., and D. Mitton, "RADIUS and IPv6",
                 RFC 3162, August 2001.

   [RFC3579]     Aboba, B. and P. Calhoun, "RADIUS (Remote
                 Authentication Dial In User Service) Support For
                 Extensible Authentication Protocol (EAP)", RFC 3579,
                 September 2003.

   [RFC3580]     Congdon, P., Aboba, B., Smith, A., Zorn, G., and J.
                 Roese, "IEEE 802.1X Remote Authentication Dial In User
                 Service (RADIUS) Usage Guidelines", RFC 3580, September
                 2003.

   [RFC3629]     Yergeau, F., "UTF-8, a transformation format of ISO
                 10646", STD 63, RFC 3629, November 2003.

   [RFC4181]     Heard, C., Ed., "Guidelines for Authors and Reviewers
                 of MIB Documents", BCP 111, RFC 4181, September 2005.

   [RFC4663]     Harrington, D., "Transferring MIB Work from IETF Bridge
                 MIB WG to IEEE 802.1 WG", RFC 4663, September 2006.

   [RFC4675]     Congdon, P., Sanchez, M., and B. Aboba, "RADIUS
                 Attributes for Virtual LAN and Priority Support", RFC
                 4675, September 2006.

   [RFC4679]     Mammoliti, V., Zorn, G., Arberg, P., and R. Rennison,
                 "DSL Forum Vendor-Specific RADIUS Attributes", RFC
                 4679, September 2006.

   [RFC4818]     Salowey, J. and R. Droms, "RADIUS Delegated-IPv6-Prefix
                 Attribute", RFC 4818, April 2007.

   [RFC4821]     Mathis, M. and J. Heffner, "Packetization Layer Path
                 MTU Discovery", RFC 4821, March 2007.

   [RFC4849]     Congdon, P., Sanchez, M., and B. Aboba, "RADIUS Filter
                 Rule Attribute", RFC 4849, April 2007.

   [RFC5080]     Nelson, D. and A. DeKok, "Common Remote Authentication
                 Dial In User Service (RADIUS) Implementation Issues and
                 Suggested Fixes", RFC 5080, December 2007.

   [RFC5090]     Sterman, B., Sadolevsky, D., Schwartz, D., Williams,
                 D., and W. Beck, "RADIUS Extension for Digest
                 Authentication", RFC 5090, February 2008.

   [RFC5176]     Chiba, M., Dommety, G., Eklund, M., Mitton, D., and B.
                 Aboba, "Dynamic Authorization Extensions to Remote
                 Authentication Dial In User Service (RADIUS)", RFC
                 5176, January 2008.

   [DOCTORS]     AAA Doctors Mailing List, www.ietf.org/mail-
                 archive/web/aaa-doctors.

   [FIPS]        FIPS 140-3 (DRAFT), "Security Requirements for
                 Cryptographic Modules",
                 http://csrc.nist.gov/publications/PubsFIPS.html.

   [IEEE-802.1Q] IEEE Standards for Local and Metropolitan Area
                 Networks: Draft Standard for Virtual Bridged Local Area
                 Networks, P802.1Q-2003, January 2003.

   [RFC5580]     Tschofenig, H., Ed., Adrangi, F., Jones, M., Lior, A.,
                 and B. Aboba, "Carrying Location Objects in RADIUS and
                 Diameter", RFC 5580, August 2009.

   [AAA-SIP]     Sterman, B., Sadolevsky, D., Schwartz, D., Williams,
                 D., and W. Beck, "RADIUS Extension for Digest
                 Authentication", Work in Progress, November 2004.

Appendix A. Design Guidelines Checklist 🎀

okay so this appendix is basically a design checklist for RADIUS attributes 💅 the vibe is: follow these guidelines and your spec is expected to reach maximum interoperability with minimal changes to existing systems ✨ no cap, that's the dream

A.1. Types Matching the RADIUS Data Model 💖

A.1.1. Transport of Basic Data Types

first question: does the data fit the basic data types from Section 2.1? 🤔 if yes, it SHOULD be encapsulated in a [RFC2865] format RADIUS attribute, or in a [RFC2865] format RADIUS VSA that uses one of the existing RADIUS data types 🦋

A.1.2. Transport of Authentication and Security Data

does the data give the RADIUS protocol authentication and/or security capabilities (the way it's outlined below)? 🔐 if so, a complex data type is fine under these circumstances:

  • complex data types that carry authentication methods which RADIUS servers are expected to parse and verify as part of an authentication process 🫶
  • complex data types that carry security information meant to increase the security of the RADIUS protocol itself 🛡️

anything carrying authentication and/or security data that a RADIUS server is NOT meant to parse is an "opaque data type", as defined in Section A.1.3 🌸

A.1.3. Opaque Data Types

okay bestie, does the attribute wrap an existing data structure defined outside of the RADIUS specs? 🧩 and can RADIUS servers (proxies included) treat it as opaque data? 👀 if both answers are yes, a complex structure MAY be used in a RADIUS specification ✨

the attribute's spec SHOULD define the encapsulating attribute as type String 💜 it SHOULD refer to an external document that defines the structure, and it SHOULD NOT define or describe the structure itself, for the reasons discussed in Section 3.2.3 🙈

A.1.4. Pre-Existing Data Types

there's a trade-off here: reuse existing formats for historical compatibility, or pick new formats for a "better" design 🍓 that trade-off doesn't always mean the "better" design has to win. so pre-existing complex data types described in Appendix B MAY be used 🌈

A.2. Improper Data Types 🙅‍♀️

this section suggests alternatives for data types that don't fall within the "basic data type" definition. Section A.2.1 covers simple data types, which should be replaced by basic data types. Section A.2.2 covers more complex data types, which should be replaced by multiple attributes using the basic data types 💅

A.2.1. Simple Data Types

does the attribute use any of these data types? 👀 if so, the data type SHOULD be replaced with the suggested alternative, or it SHOULD NOT be used at all:

  • Signed integers of any size. SHOULD NOT be used. It SHOULD be replaced with one or more unsigned integer attributes. The attribute's definition can hold the information that would otherwise go into the sign value of the integer 🔢
  • 8-bit unsigned integers. SHOULD be replaced with a 32-bit unsigned integer. There is insufficient justification to save three bytes 🙃
  • 16-bit unsigned integers. SHOULD be replaced with a 32-bit unsigned integer. There is insufficient justification to save two bytes 🙃
  • Unsigned integers of size other than 32 bits. SHOULD be replaced by a 32-bit unsigned integer. There is insufficient justification to define a new size of integer 🚫
  • Integers of any size in non-network byte order. SHOULD be replaced by a 32-bit unsigned integer in network byte order. There is no reason to transport integers in any format other than network byte order 🌐
  • Multi-field text strings. Each field SHOULD be encapsulated in a separate attribute 🧃
  • Polymorphic attributes. Multiple attributes, each with a static data type, SHOULD be defined instead 🦄
  • Nested attribute-value pairs (AVPs). attributes should be defined in a flat typespace 🥞

A.2.2. More Complex Data Types

does the attribute:

  • define a complex data type that isn't described in Appendix B? 🤨
  • define a type that a RADIUS server and/or client is expected to parse, validate, or create the contents of via a dynamic computation (i.e., a type that cannot be treated as opaque data, Section A.1.3)? 🧮
  • involve functionality that could be implemented without code changes on both the client and server (i.e., a type that doesn't require dynamic computation and verification, like the ones done for authentication or security attributes)? 🛠️

if so, this data type SHOULD be replaced with simpler types, as discussed in Appendix A.2.1 🫧 see also Section 2.1 for a discussion of why complex types are problematic 💀

A.3. Vendor-Specific Formats 🏷️

does the spec contain Vendor-Specific Attributes that match any of these criteria? 👀 if so, the VSA encoding should be replaced with the [RFC2865], Section 5.26 encoding, or it should not be used at all:

  • Vendor types of more than 8 bits. SHOULD NOT be used. Vendor types of 8 bits SHOULD be used instead 🙅‍♀️
  • Vendor lengths of less than 8 bits (i.e., zero bits). SHOULD NOT be used. Vendor lengths of 8 bits SHOULD be used instead 🙅‍♀️
  • Vendor lengths of more than 8 bits. SHOULD NOT be used. Vendor lengths of 8 bits SHOULD be used instead 🙅‍♀️
  • Vendor-specific contents that are not in Type-Length-Value format. SHOULD NOT be used. Vendor-Specific Attributes SHOULD be in Type-Length-Value format 📦

in general, Vendor-Specific Attributes SHOULD follow the encoding suggested in Section 5.26 of [RFC2865] 🎀 and vendor extensions to non-standard encodings are NOT RECOMMENDED, since they can negatively affect interoperability 😭

Heads up: the NOT RECOMMENDED bit above is the big one. Don't go inventing your own non-standard VSA encodings, bestie 🚨

A.4. Changes to the RADIUS Operational Model 💅

Okay bestie, the big question here is: does your spec change how RADIUS normally operates? 🤔 If it does, then another method of reaching your design goals SHOULD be used instead 🙅‍♀️ Here are the potential problem areas to watch for:

  • Defining new commands in RADIUS using attributes. New commands MUST be added by allocating a new Code, not by using an attribute 🚫 This also covers new commands made by overloading the Service-Type Attribute to define new values that change how Access-Request packets work. No sneaking it in, periodt 💀
  • Using RADIUS as a transport protocol for data unrelated to authentication, authorization, or accounting. Using RADIUS to carry authentication methods like EAP is explicitly permitted 🎀 even when those methods need to move relatively large amounts of data. Carrying opaque AAA-related data is allowed too, as covered in Section 3.2.3. But if your spec doesn't relate to AAA at all, then RADIUS SHOULD NOT be used 🙈
  • Assuming support for packet lengths greater than 4096 octets. Attribute designers cannot assume that RADIUS implementations can handle packets bigger than 4096 octets 📏 If a spec could lead to a RADIUS packet larger than 4096 octets, then the alternatives in Section 3.3 SHOULD be considered 🧐
  • Stateless operation. RADIUS is stateless ✨ so documents that need stateful protocol behavior without using the State Attribute need to be redesigned 🔄
  • Provisioning of service in an Access-Reject. Nope, this is not permitted, and it MUST NOT be used 🛑 If limited access needs to be provided, an Access-Accept with appropriate authorizations can be used instead 💖
  • Provisioning of service in a Disconnect-Request. Also not permitted, and it MUST NOT be used 🚫 If limited access needs to be provided, a CoA-Request [RFC5176] with appropriate authorizations can do the job instead 🦋
  • Lack of user authentication or authorization restrictions. In an authorization check where there's no demonstration of a live user, confidential data cannot be returned 🔒 Where there's a link to a previous user authentication, the State Attribute SHOULD be present 🫶
  • Lack of per-packet integrity and authentication. It is expected that documents will support per-packet integrity and authentication 🛡️
  • Modification of RADIUS packet sequences. In RADIUS, each request gets its own packet and elicits a single response sent back to the requester 📦 Since changing this paradigm is likely to require major modifications to RADIUS client and server implementations, they SHOULD be avoided if possible 🙏

For further details, see Section 3.1. 📚

A.5. Allocation of Attributes 🎀

Does the attribute have a limited scope of applicability, as outlined below? If so, then the attributes SHOULD be allocated from the vendor space rather than requesting allocation from the standard space ✨

  • attributes intended for a vendor to support their own systems and not suitable for general usage 🏢
  • attributes relying on data types not defined within RADIUS 🧩
  • attributes intended primarily for use within an SDO 🏛️
  • attributes intended primarily for use within a group of SDOs 👯

Note that the points listed above do not relax the recommendations discussed in this document 🙌 Instead, they recognize that the RADIUS data model has limitations. In certain situations where interoperability can be strongly constrained by the SDO or vendor, an expanded data model MAY be used. It is RECOMMENDED, however, that the RADIUS data model be used, even when it is marginally less efficient than alternatives.

When attributes are used primarily within a group of SDOs, and are not applicable to the wider Internet community, we expect that one SDO will be responsible for allocation from their own private vendor space 💜

Appendix B. Complex Attributes 🧁

This appendix summarizes RADIUS attributes with complex data types that are defined in existing RFCs 📖

This appendix is published for informational purposes only 🌸 and reflects the usage of attributes with complex data types at the time of the publication of this document.

B.1. CHAP-Password 🔐

[RFC2865], Section 5.3 defines the CHAP-Password Attribute, which is sent from the RADIUS client to the RADIUS server in an Access-Request. The data type of the CHAP Identifier is not given, only the one-octet length:

    0                   1                   2
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-
   |     Type      |    Length     |  CHAP Ident   |  String ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-

Since this is an authentication attribute, code changes are required on the RADIUS client and server to support it, regardless of the attribute format. Therefore, this complex data type is acceptable in this situation ✅

B.2. CHAP-Challenge 🧩

[RFC2865], Section 5.40 defines the CHAP-Challenge Attribute, which is sent from the RADIUS client to the RADIUS server in an Access-Request. While the data type of the CHAP Identifier is given, the text also says:

If the CHAP challenge value is 16 octets long it MAY be placed in the Request Authenticator field instead of using this attribute.

Defining attributes to contain values taken from the RADIUS packet header is NOT RECOMMENDED 🙅‍♀️ Attributes should have values that are packed into a RADIUS AVP 📦

B.3. Tunnel-Password 🔑

[RFC2868], Section 3.5 defines the Tunnel-Password Attribute, which is sent from the RADIUS server to the client in an Access-Accept. This attribute includes Tag and Salt fields, as well as a String field that consists of three logical sub-fields: the Data-Length (required and one octet), Password sub-fields (required), and the optional Padding sub-field. The attribute appears as follows:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Type      |    Length     |     Tag       |   Salt
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
      Salt (cont)  |   String ...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Since this is a security attribute, code changes are required on the RADIUS client and server to support it, regardless of the attribute format. However, while use of a complex data type is acceptable in this situation, the design of the Tunnel-Password Attribute is problematic from a security perspective 🚨

Heads up, bestie: it uses MD5 as a cipher and provides a password to a NAS, potentially without proper authorization. Handle with care 😭

B.4. ARAP-Password 🍎

[RFC2869], Section 5.4 defines the ARAP-Password Attribute, which is sent from the RADIUS client to the server in an Access-Request. It contains four 4-octet values instead of having a single Value field:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Type      |    Length     |             Value1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                   |             Value2
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                   |             Value3
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                   |             Value4
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

As with the CHAP-Password Attribute, this is an authentication attribute that would have required code changes on the RADIUS client and server, regardless of format 🔁

B.5. ARAP-Features 🦋

[RFC2869], Section 5.5 defines the ARAP-Features Attribute, which is sent from the RADIUS server to the client in an Access-Accept or Access-Challenge. It contains a compound string of two single octet values, plus three 4-octet values, which the RADIUS client encapsulates in a feature flags packet in the Apple Remote Access Protocol (ARAP):

   0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Type      |    Length     |     Value1    |    Value2     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                           Value3                              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                           Value4                              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                           Value5                              |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Unlike the previous attributes, this attribute contains no encrypted component, nor is it directly involved in authentication. The individual sub-fields therefore could have been encapsulated in separate attributes 🧠

While the contents of this attribute are intended to be placed in an ARAP packet, the fields need to be set by the RADIUS server. Using standard RADIUS data types would have simplified RADIUS server implementations and subsequent management. The current form of the attribute requires either the RADIUS server implementation or the RADIUS server administrator to understand the internals of the ARAP protocol 🥺

B.6. Connect-Info 💅

okay so [RFC2869], Section 5.11 is where the Connect-Info Attribute lives, and it's used to say what kind of connection we're dealing with ✨

    0                   1                   2
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Type      |    Length     |     Text...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

ngl the type is Text 🎀 but the rest of the description makes it clear it's really a complex attribute 🔥

      The Text field consists of UTF-8 encoded 10646 [8] characters.
      The connection speed SHOULD be included at the beginning of the
      first Connect-Info attribute in the packet.  If the transmit and
      receive connection speeds differ, they may both be included in the
      first attribute with the transmit speed first (the speed the NAS
      modem transmits at), a slash (/), the receive speed, then
      optionally other information.

      For example, "28800 V42BIS/LAPM" or "52000/31200 V90"

      More than one Connect-Info attribute may be present in an
      Accounting-Request packet to accommodate expected efforts by ITU
      to have modems report more connection information in a standard
      format that might exceed 252 octets.

So the Text field is UTF-8 encoded 10646 [8] characters 🦋 and the connection speed SHOULD be included at the very beginning of the first Connect-Info attribute in the packet 💜 If transmit and receive speeds are different, they MAY both be included in that first attribute, with the transmit speed first (the speed the NAS modem transmits at), then a slash (/), then the receive speed, then optionally other info 🌸

Examples, bestie: "28800 V42BIS/LAPM" or "52000/31200 V90" 😭🫶

Also, more than one Connect-Info attribute can show up in an Accounting-Request packet, because ITU is working on letting modems report more connection info in a standard format, and that could go past 252 octets 🌈

This attribute has no encrypted part and isn't directly involved in authentication 🙈 Honestly the sub-fields could've just been split into separate attributes 💅

BUT since the definition points at possible standardization work inside ITU, Connect-Info can also be treated as opaque data whose definition lives somewhere else 🧚 That means it could qualify for the exception described in Section 3.2.4 ✨

B.7. Framed-IPv6-Prefix 👑

Section 2.3 of [RFC3162] defines the Framed-IPv6-Prefix Attribute 💖 and Section 3 of [RFC4818] reuses this same format for the Delegated-IPv6-Prefix Attribute 🌈 These attributes are sent from the RADIUS server to the client in an Access-Accept 🎀

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Type      |    Length     |  Reserved     | Prefix-Length |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                Prefix
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                Prefix
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                Prefix
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
                                Prefix                             |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

The sub-fields in these attributes are strongly related 🧚 and there was no previous definition of this data structure that could be referenced 😭 Supporting this attribute needs code changes on both the client and the server, because a new data type is being defined 💅 In this case, it looks acceptable to encode them in one attribute ✨

B.8. Egress-VLANID 🦋

[RFC4675], Section 2.1 defines the Egress-VLANID Attribute 💜 and it can be sent by a RADIUS client or server 🌸

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Type      |    Length     |            Value
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
           Value (cont)            |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

It looks superficially like an Integer 🙈 but the Value field is actually a packed structure, like this:

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |  Tag Indic.   |        Pad            |       VLANID          |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

The length of the VLANID field is defined by the [IEEE-802.1Q] specification 🎀 The Tag Indicator field is either 0x31 or 0x32, so it stays compatible with the Egress-VLAN-Name, which we'll get to below 🌈 The complex structure of Egress-VLANID overlaps with the base Integer data type, which means a RADIUS server needs no code changes to support it 🔥 The NAS does need code changes, if only to enforce the VLAN ID 👑

Given the IEEE VLAN requirements and how limited the RADIUS data model is, the chosen method is probably the best of the alternatives 💖

B.9. Egress-VLAN-Name 🧚

[RFC4675], Section 2.3 defines the Egress-VLAN-Name Attribute 🌸 and it can be sent by a RADIUS client or server 💅

    0                   1                   2                   3
    0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |     Type      |    Length     |   Tag Indic.  |   String...
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

The Tag Indicator is either the character '1' or '2' 🦋 In ASCII those map to the same values as the Tag Indicator in Egress-VLANID above 💜 The complex structure of this attribute is fine for the same reasons given for Egress-VLANID ✨

B.10. Digest-* 😭

[RFC5090] tries to standardize the functionality provided by an expired Internet-Draft [AAA-SIP] 🙈 That draft improperly uses two attributes from the standard space without having been assigned them by IANA 💀 This self-allocation is forbidden, as described in Section 2 🔥 The document also uses nested attributes, which Section 2.1 discourages 🫶 The updated document uses basic data types and allocates nearly 20 attributes in the process 🌈

The document has seen wide-spread implementation 👑 but [RFC5090] itself hasn't 🌸 One explanation could be that implementors disagreed with the trade-offs made in the updated specification 💅 It might have been better to just document the existing format and request IANA allocation of two attributes 💖 That design would have used nested attributes, but it may have gained more wide-spread implementation ✨

Acknowledgments 🫶

We would like to acknowledge David Nelson, Bernard Aboba, Emile van Bergen, Barney Wolff, Glen Zorn, Avi Lior, and Hannes Tschofenig for contributions to this document 🌈💖

Authors' Addresses 🎀

Alan DeKok (editor) The FreeRADIUS Server Project http://freeradius.org/

EMail: aland@freeradius.org

Greg Weber Knoxville, TN 37932 USA

EMail: gdweber@gmail.com

📦 where this page comes from