--- 1/draft-ietf-radext-datatypes-02.txt 2016-05-06 18:15:56.175569115 -0700 +++ 2/draft-ietf-radext-datatypes-03.txt 2016-05-06 18:15:56.239570707 -0700 @@ -1,21 +1,21 @@ Network Working Group DeKok, Alan INTERNET-DRAFT FreeRADIUS Updates: 2865,3162,6158,6572 Category: Standards Track - -2 November 2015 + +6 May 2016 Data Types in the Remote Authentication Dial-In User Service Protocol (RADIUS) - draft-ietf-radext-datatypes-02.txt + draft-ietf-radext-datatypes-03.txt 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 RFC 2865. We provide an IANA registry for the data types, and update the @@ -37,25 +37,25 @@ and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. - This Internet-Draft will expire on May 2, 2016. + This Internet-Draft will expire on November 6, 2016. Copyright Notice - Copyright (c) 2015 IETF Trust and the persons identified as the + Copyright (c) 2016 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 @@ -71,26 +71,26 @@ 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 ................ 7 2.1.4. Defining a New Data Type ....................... 8 2.2. Implementation Use of Data Types .................... 9 3. Data Type Definitions .................................... 11 3.1. integer ............................................. 12 3.2. enum ................................................ 12 - 3.3. ipv4addr ............................................ 13 - 3.4. time ................................................ 13 - 3.5. text ................................................ 14 - 3.6. string .............................................. 15 - 3.7. concat .............................................. 16 - 3.8. ifid ................................................ 17 + 3.3. time ................................................ 13 + 3.4. text ................................................ 13 + 3.5. string .............................................. 14 + 3.6. concat .............................................. 15 + 3.7. ifid ................................................ 16 + 3.8. ipv4addr ............................................ 17 3.9. ipv6addr ............................................ 17 3.10. ipv6prefix ......................................... 18 3.11. ipv4prefix ......................................... 19 3.12. integer64 .......................................... 20 3.13. tlv ................................................ 21 3.14. vsa ................................................ 23 3.15. extended ........................................... 24 3.16. long-extended ...................................... 25 3.17. evs ................................................ 27 4. Updated Registries ....................................... 29 @@ -192,21 +192,21 @@ 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 + 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 @@ -253,28 +253,29 @@ from the RADIUS Data Type registry. The specification may, of course, define a new data type and use it 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 code, 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 the standard - space, or from one of the extended spaces. This allocation decision - is made after the specification has been accepted for publication. - That allocation strongly affects the format of the attribute header, - making it nearly impossible to create the correct ASCII art prior to - final publication. Allocation from the different spaces also changes - the value of the Length field, also making it difficult to define it - correctly prior to final publication of the document. + more problematic. An attribute can be allocated from any of the + extended spaces, with more than one option for 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 esstentially impossible to create the + correct ASCII art prior to final publication. Allocation from the + different spaces also changes the value of the Length field, also + making it difficult to define it correctly prior to final publication + of the document. It is therefore RECOMMENDED that "ASCII art" diagrams not be used for new RADIUS attribute specifications. 2.1.3. Format of Attribute Definitions When defining a new attribute, the following fields SHOULD be given: Description @@ -329,41 +331,41 @@ 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 to be determined or "TBD" in specifications. That number is assigned by IANA. - The "Format" field SHOULD be defined with "Ascii art" in order to + 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 guideliness 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 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 2.6. It is RECOMMENDED that such attributes be + defined in Section 3.6. It is RECOMMENDED that such attributes be treated as "invalid attributes", as defined in [RFC6929] Section 2.8. Where the contents of a data type do not match the definition, implementations MUST treat the 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". @@ -408,35 +410,35 @@ 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 inter-dependencies, the simplest data type is given first, and dependent ones are given later. We do not create specific data types for the "tagged" attributes - defines in [RFC2868]. That specification defines the "tagged" + 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 complex structure, such as CHAP-Password, ARAP-Features, or Location- - Capable. We need to strike a balance between correcting earlier + Information. 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 [RFC6969] were used to make this + guidelines given in Section 6.3 of [RFC6929] were used to make this determination. 3.1. integer The "integer" data type encodes a 32-bit unsigned integer in network byte order. Where the range of values for a particular attribute is limited to a sub-set of the values, specifications MUST define the valid range. Attributes with Values outside of the allowed ranges SHOULD be treated as "invalid attributes". @@ -482,79 +484,51 @@ Four octets Format 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Value | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -3.3. ipv4addr - - The "ipv4addr" data type encodes an IPv4 address in network byte - order. Where the range of address for a particular attribute is - limited to a sub-set of possible addresses, specifications MUST - define the valid range(s). Attributes with Addresses outside of the - allowed range(s) SHOULD be treated as "invalid attributes". - - Name - - ipv4addr - - Value - - 3 - - Length - - Four octets - - Format - - 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 - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Address | - +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - -3.4. time +3.3. time The "time" data type encodes time as a 32-bit unsigned value in network byte order and in seconds since 00:00:00 UTC, January 1, - 1970. We note that dates before the year 2015 are likely to be - erroneous. + 1970. We note that dates before the year 2016 are likely to indicate + configuration errors, or lack of access to the correct time. Note that the "time" attribute is defined to be unsigned, which means it is not subject to a signed integer overflow in the year 2038. Name time Value - 4 + 3 Length Four octets Format 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Time | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ -3.5. text +3.4. text The "text" data type encodes UTF-8 text [RFC3629]. The maximum length of the text is given by the encapsulating attribute. Where the range of lengths for a particular attribute is limited to a sub- set of possible lengths, specifications MUST define the valid range(s). Attributes with length outside of the allowed values SHOULD be treated as "invalid attributes". Where the text is intended to carry data in a particular format, (e.g. Framed-Route), the format MUST be given. The specification @@ -567,35 +541,35 @@ (hex 00). The Attribute has a Length field and does not use a terminator. Texts of length zero (0) MUST NOT be sent; omit the entire attribute instead. Name text Value - 5 + 4 Length One or more octets. Format 0 0 1 2 3 4 5 6 7 +-+-+-+-+-+-+-+- | Value ... +-+-+-+-+-+-+-+- -3.6. string +3.5. string The "string" data type encodes binary data, as a sequence of undistinguished octets. Where the range of lengths for a particular attribute is limited to a sub-set of possible lengths, specifications MUST define the valid range(s). Attributes with length outside of the allowed values SHOULD be treated as "invalid attributes". Note that the "string" data type does not terminate with a NUL octet (hex 00). The Attribute has a Length field and does not use a terminator. Strings of length zero (0) MUST NOT be sent; omit the @@ -611,39 +585,40 @@ There is little reason to define a new RADIUS data type for only one attribute. However, where the complex data type cannot be represented as TLVs, and is expected to be used in many attributes, a new data type SHOULD be defined. These requirements are stronger than [RFC6158], which makes the above encapsulation a "SHOULD". This document defines data types for use in RADIUS, so there are few reasons to avoid using them. Name + string Value - 6 + 5 Length One or more octets. Format 0 0 1 2 3 4 5 6 7 +-+-+-+-+-+-+-+- | Octets ... +-+-+-+-+-+-+-+- -3.7. concat +3.6. concat The "concat" data type permits the transport of more than 253 octets of data in a "standard space" [RFC6929] attribute. It is otherwise identical to the "string" data type. If multiple attributes of this data type are contained in a packet, all attributes of the same type code MUST be in order and they MUST be consecutive attributes in the packet. The amount of data transported in a "concat" data type can be no more @@ -657,49 +632,49 @@ It MUST NOT be used for attributes in the "short extended space" or the "long extended space". It MUST NOT be used in any field or subfields of the following data types: "tlv", "vsa", "extended", "long-extended", or "evs". Name concat Value - 7 + + 6 Length One or more octets. Format 0 0 1 2 3 4 5 6 7 +-+-+-+-+-+-+-+- | Octets ... +-+-+-+-+-+-+-+- -3.8. ifid +3.7. ifid The "ifid" data type encodes an Interface-Id as an 8-octet string in network byte order. Name ifid Value - 8 + 7 Length - Eight octets Format 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Interface-ID ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... Interface-ID | @@ -698,20 +673,48 @@ Format 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Interface-ID ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... Interface-ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ +3.8. ipv4addr + + The "ipv4addr" data type encodes an IPv4 address in network byte + order. Where the range of address for a particular attribute is + limited to a sub-set of possible addresses, specifications MUST + define the valid range(s). Attributes with Addresses outside of the + allowed range(s) SHOULD be treated as "invalid attributes". + + Name + + ipv4addr + + Value + + 8 + + Length + + Four octets + + Format + + 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 + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + | Address | + +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ + 3.9. ipv6addr The "ipv6addr" data type encodes an IPv6 address in network byte order. Where the range of address for a particular attribute is limited to a sub-set of possible addresses, specifications MUST define the valid range(s). Attributes with Addresses outside of the allowed range(s) SHOULD be treated as "invalid attributes". Name @@ -808,43 +812,42 @@ Name ipv4prefix Value 11 Length - At least two, and no more than eighteen octets. + six octets Format 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 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ - | Reserved | Prefix-Len| Prefix ... + | Reserved | Prefix-Length | Prefix ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... Prefix | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Subfields Reserved This field, which is reserved and MUST be present, is always set to zero. - Prefix-Length - - A 6-bit unsigned integer containing the length of the prefix, - in bits. The values MUST be no larger than 32. + Prefix-Length < + The length of the prefix, in bits. The values MUST be no + larger than 32. Prefix The Prefix field is 4 octets in length. Bits outside of the Prefix-Length MUST be zero. Unlike the "ipv6prefix" data type, this field is fixed length. If the address is all zeros (i.e. "0.0.0.0", then the Prefix-Length MUST be set to 32. 3.12. integer64 @@ -929,21 +931,21 @@ TLV-Length The TLV-Length field is one octet, and indicates the length of this TLV including the TLV-Type, TLV-Length and TLV-Value fields. It MUST have a value between 3 and 255. If a client or server receives a TLV with an invalid TLV-Length, then the attribute which encapsulates that TLV MUST be considered to be an "invalid attribute", and handled as per [RFC6929] Section 2.8. - TLVs having TLV-Length of zero (0) MUST NOT be sent; omit the + TLVs having TLV-Length of two (2) MUST NOT be sent; omit the entire TLV instead. TLV-Data The TLV-Data field is one or more octets and contains information specific to the Attribute. The format and length of the TLV-Data field is determined by the TLV-Type and TLV- Length fields. The TLV-Data field MUST contain only known RADIUS data types. @@ -1257,26 +1261,26 @@ Reference The specification where the data type was defined. The initial contents of the registry are as follows. Value Description Reference ----- ----------- ---------------- 1 integer [RFC2865], TBD 2 enum [RFC2865], TBD - 3 ipv4addr [RFC2865], TBD - 4 time [RFC2865], TBD - 5 text [RFC2865], TBD - 6 string [RFC2865], TBD - 7 concat TBD - 8 ifid [RFC3162], TBD + 3 time [RFC2865], TBD + 4 text [RFC2865], TBD + 5 string [RFC2865], TBD + 6 concat TBD + 7 ifid [RFC3162], TBD + 8 ipv4addr [RFC2865], TBD 9 ipv6addr [RFC3162], TBD 10 ipv6prefix [RFC3162], TBD 11 ipv4prefix [RFC6572], TBD 12 integer64 [RFC6929], TBD 13 tlv [RFC6929], TBD 14 evs [RFC6929], TBD 15 extended [RFC6929], TBD 16 long-extended [RFC6929], TBD 4.2. Updates to the Attribute Type Registry @@ -1533,25 +1537,25 @@ implementation work is therefore simpler, and is more likely to be correct. The goal of this specification is to reduce ambiguities in the RADIUS protocol, which we believe will lead to more robust and more secure implementations. 6. IANA Considerations IANA is instructed to create one new registry as described above in - Section 3.1. The "TBD" text in that section should be replaced with + Section 4.1. The "TBD" text in that section should be replaced with the RFC number of this document when it is published. IANA is instructed to update the RADIUS Attribute Type registry, as - described above in Section 3.2. + described above in Section 4.2. IANA is instructed to require that all allocation requests in the RADIUS Attribute Type Registry contain a "Data Type" field. That field is required to contain one of the "Data Type" names contained in the RADIUS Data Type registry. IANA is instructed to require that updates to the RADIUS Data Type registry contain the following fields, with the associated instructions: @@ -1617,18 +1621,18 @@ [RFC7499] Perez-Mendez A., et al, "Support of Fragmentation of RADIUS Packets", RFC 7499, April 2015. [PEN] http://www.iana.org/assignments/enterprise-numbers Acknowledgments - Stuff + Thanks to the RADEXT WG for patience and reviews of this document. Authors' Addresses Alan DeKok The FreeRADIUS Server Project Email: aland@freeradius.org