--- 1/draft-ietf-radext-datatypes-00.txt 2015-09-04 10:14:59.769804819 -0700 +++ 2/draft-ietf-radext-datatypes-01.txt 2015-09-04 10:14:59.825806178 -0700 @@ -1,21 +1,21 @@ Network Working Group DeKok, Alan INTERNET-DRAFT FreeRADIUS Updates: 2865,3162,6158,6572 Category: Standards Track - -20 August 2015 + +4 September 2015 Data Types in the Remote Authentication Dial-In User Service Protocol (RADIUS) - draft-ietf-radext-datatypes-00.txt + draft-ietf-radext-datatypes-01.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,21 +37,21 @@ 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 February 20, 2016. + This Internet-Draft will expire on March 4, 2016. Copyright Notice Copyright (c) 2015 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 @@ -63,44 +63,44 @@ Table of Contents 1. Introduction ............................................. 4 1.1. Specification use of Data Types ..................... 4 1.2. Implementation use of Data Types .................... 4 1.3. Requirements Language ............................... 5 2. Data Type Definitions .................................... 6 2.1. integer ............................................. 7 2.2. enum ................................................ 8 - 2.3. ipv4addr ............................................ 8 + 2.3. ipv4addr ............................................ 9 2.4. time ................................................ 9 2.5. text ................................................ 10 - 2.6. string .............................................. 10 - 2.7. concat .............................................. 11 - 2.8. ifid ................................................ 12 + 2.6. string .............................................. 11 + 2.7. concat .............................................. 12 + 2.8. ifid ................................................ 13 2.9. ipv6addr ............................................ 13 2.10. ipv6prefix ......................................... 14 2.11. ipv4prefix ......................................... 15 2.12. integer64 .......................................... 16 - 2.13. tlv ................................................ 16 + 2.13. tlv ................................................ 17 2.14. vsa ................................................ 18 - 2.15. extended ........................................... 19 - 2.16. long-extended ...................................... 20 - 2.17. evs ................................................ 22 + 2.15. extended ........................................... 20 + 2.16. long-extended ...................................... 21 + 2.17. evs ................................................ 23 3. Updated Registries ....................................... 24 3.1. Create a Data Type Registry ......................... 24 3.2. Updates to the Attribute Type Registry .............. 25 4. Suggestions for Specifications ........................... 30 5. Security Considerations .................................. 31 -6. IANA Considerations ...................................... 31 -7. References ............................................... 31 - 7.1. Normative References ................................ 31 - 7.2. Informative References .............................. 32 +6. IANA Considerations ...................................... 32 +7. References ............................................... 32 + 7.1. Normative References ................................ 32 + 7.2. Informative References .............................. 33 1. Introduction RADIUS specifications have historically defined attributes in terms of name, type value, and data type. Of these three pieces of information, only the type value is managed by IANA. There is no management of, or restriction on, the attribute name, as discussed in [RFC6929] Section 2.7.1. There is no management of data type name or definition. This document defines an IANA registry for data types, and updates the RADIUS Attribute Type registry to use those newly @@ -141,26 +141,33 @@ RADIUS implementations often use "dictionaries" to map attribute names to type values, and to define data types for each attribute. The data types in the dictionaries are defined by each implementation, but correspond to the "ad hoc" data types used in the specifications. In effect, implementations have seen the need for well-defined data types, and have created them. It is time for RADIUS specifications to follow this practice. - This document requires no changes to any RADIUS implementation, past, + This document mandates no changes to any RADIUS implementation, past, present, or future. It instead documents existing practice, in order to simplify the process of writing RADIUS specifications, to clarify the interpretation of RADIUS standards, and to improve the communication between specification authors and IANA. + This document suggests that implementations SHOULD use the data types + defined here, in preference to any "ad hoc" data types currently in + use. This suggestion should have minimal effect on implementations, + as most "ad hoc" data types are compatible with the ones defined + here. Any difference will typically be limited to the name of the + data type. + 1.3. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. 2. Data Type Definitions This section defines the new data types. For each data type, it gives a definition, a name, a number, a length, and an encoding @@ -173,45 +180,51 @@ previous specifications. In some cases, a different name has been chosen. The change of name is sometimes required to avoid ambiguity (i.e. "address" versus "Address"). Otherwise, the new name has been chosen to be compatible with [RFC2865], or with use in common implementations. In some cases, new names are chosen to clarify the interpretation of the data type. The numbers assigned herein for the data types have no meaning other than to permit them to be tracked by IANA. As RADIUS does not encode information about data types in a packet, the numbers assigned to a - data type will never occur in a packet. + data type will never occur in a packet. It is RECOMMENDED that new + implementations use the names defined herein, in order to avoid + confusion. Existing implementations may choose to use the names + defined herein, 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, as discussed 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. + 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 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. Implementations not supporting a particular data type MUST treat - attributes of that data type as being of data type "string". See - Section 2.6, below for a definition of the "string" data type. + attributes of that data type as being of data type "string", as + defined in Section 2.6. It is RECOMMENDED that such attributes be + treated as "invalid attributes", as defined in [RFC6929] Section 2.8. The definitions below use specialized names for various fields of attributes and data types. These names serve to address ambiguity of the field names in previous specifications. For example, the term "Value" is used in [RFC2865] Section 5 to define a field which carries the contents of attribute. It is then used in later sections as the sub-field of attribute contents. The result is that the field is defined as recursively containing itself. Similarly, "String" is used both as a data type, and as a sub-field of other data types. @@ -220,37 +233,38 @@ is the following term: Attr-Data The "Value" field of an Attribute as defined in [RFC2865] Section 5. The contents of this field MUST be a valid data type as defined in the RADIUS Data Type registry. In this document, we use the term "Value" only to refer to the contents of a data type, where that data type cannot carry other data - types. In other cases, we refer to the contents of a data type as - "Type-Data", to distinguish it from data of other types. For - example, a data type "vsa" will contain a data field called "VSA- - Data". + types. In other cases, we refer to the contents of a data type with + a type-specific name, in order to distinguish it from data of other + types. For example, the data type "vsa" will contain a data field + called "VSA-Data". These terms are used in preference to the term "String", which was used in multiple incompatible ways. It is RECOMMENDED that future - specifications use the new terms in order to maintain consistent - definitions, and to avoid ambiguities. + specifications use these names, and the same naming scheme for new + types, in order to maintain consistent definitions, and to avoid + ambiguities. 2.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. Values outside of the allowed ranges SHOULD be treated - as invalid. + valid range. Attributes with Values outside of the allowed ranges + SHOULD be treated as "invalid attributes". Name integer Number 1 Length @@ -264,21 +278,22 @@ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Value | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2.2. enum The "enum" data type encodes a 32-bit unsigned integer in network byte order. It differs from the "integer" data type only in that it is used to define enumerated types, such as Service-Type. Specifications MUST define a valid set of enumerated values, along - with a unique name for each value. + with a unique name for each value. Attributes with Values outside of + the allowed enumerations SHOULD be treated as "invalid attributes". Name enum Number 2 Length @@ -291,24 +306,25 @@ 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2.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). Values outside of the allowed range - SHOULD be treated as invalid. + define the valid range(s). Attributes with Values outside of the + allowed range(s) SHOULD be treated as "invalid attributes". Name + ipv4addr Number 3 Length Four octets @@ -317,21 +333,21 @@ 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 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2.4. 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 2013 are likely to be + 1970. We note that dates before the year 2015 are likely to be erroneous. 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 Number @@ -349,26 +364,34 @@ +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Time | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2.5. 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). + range(s). Attributes with length outside of the allowed values + SHOULD be treated as "invalid attributes". - Note that the "text" type does not terminate with a NUL octet (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. + Where the text is intended to carry data in a particular format, + (e.g. Framed-Route), the format MUST be given. The specification + SHOULD describe the format in a machine-readable way, such as via + Augmented Backus-Naur Form (ABNF). Attributes with values not + matching the defined format SHOULD be treated as "invalid + attributes". + + Note that the "text" data type does not terminate with a NUL octet + (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 Number 5 Length @@ -372,30 +395,32 @@ 5 Length One or more octets. Format 0 0 1 2 3 4 5 6 7 + +-+-+-+-+-+-+-+- | Value ... +-+-+-+-+-+-+-+- 2.6. 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). + 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 entire attribute instead. Where there is a need to encapsulate complex data structures, and TLVs cannot be used, the "string" data type MUST be used. This requirement include encapsulation of data structures defined outside of RADIUS, which are opaque to the RADIUS infrastucture. It also @@ -499,21 +524,22 @@ | Interface-ID ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... Interface-ID | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2.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). + define the valid range(s). Attributes with Values outside of the + allowed range(s) SHOULD be treated as "invalid attributes". Name ipv6addr Number 9 Length @@ -530,21 +555,28 @@ ... Address ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... Address ... +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ... Address | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2.10. ipv6prefix The "ipv6prefix" data type encodes an IPv6 prefix, using both a - prefix length and an IPv6 address in network byte order. + prefix length and an IPv6 address in network byte order. Where the + range of prefixes for a particular attribute is limited to a sub-set + of possible prefixes, specifications MUST define the valid range(s). + Attributes with Values outside of the allowed range(s) SHOULD be + treated as "invalid attributes". + + Attributes with a Prefix-Length field having value greater than 128 + SHOULD be treated as "invalid attributes". Name ipv6prefix Number 10 Length @@ -573,26 +605,33 @@ set to zero. Prefix-Length The length of the prefix, in bits. At least 0 and no larger than 128. Prefix The Prefix field is up to 16 octets in length. Bits outside of - the Prefix-Length, if included, must be zero. + the Prefix-Length, if included, MUST be zero. 2.11. ipv4prefix The "ipv4prefix" data type encodes an IPv4 prefix, using both a - prefix length and an IPv4 address in network byte order. + prefix length and an IPv4 address in network byte order. Where the + range of prefixes for a particular attribute is limited to a sub-set + of possible prefixes, specifications MUST define the valid range(s). + Attributes with Values outside of the allowed range(s) SHOULD be + treated as "invalid attributes". + + Attributes with a Prefix-Length field having value greater than 32 + SHOULD be treated as "invalid attributes". Name ipv4prefix Number 11 Length @@ -617,30 +656,31 @@ 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 The Prefix field is 4 octets in length. Bits outside of the - Prefix-Length must be zero. Unlike the "ipv6prefix" data type, + 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. 2.12. integer64 The "integer64" data type encodes a 64-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(s). + define the valid range(s). Attributes with Values outside of the + allowed range(s) SHOULD be treated as "invalid attributes". Name integer64 Number 12 Length @@ -729,20 +769,24 @@ The TLV-Data field MUST NOT contain any of the following data types: "concat", "vsa", "extended", "long-extended", or "evs". 2.14. vsa The "vsa" data type encodes Vendor-Specific data, as given in [RFC2865] Section 5.26. It is used only in the Attr-Data field of a Vendor-Specific Attribute. It MUST NOT appear in the contents of any other data type. + Where an implementation determines that an attribute of data type + "vsa" contains data which does not match the expected format, it + SHOULD treat that attribute as being an "invalid attribute". + Name vsa Number 14 Length @@ -768,23 +812,23 @@ VSA-Data The VSA-Data field is one or more octets. The actual format of the information is site or application specific, and a robust implementation SHOULD support the field as undistinguished octets. The codification of the range of allowed usage of this field is outside the scope of this specification. - It SHOULD be encoded as a sequence of "tlv" fields. The - interpretation of the TLV-Type and TLV-Data fields are - dependent on the vendor's definition of that attribute. + The "vsa" data type SHOULD contain as a sequence of "tlv" data + types. The interpretation of the TLV-Type and TLV-Data fields + are dependent on the vendor's definition of that attribute. The "vsa" data type MUST be used as contents of the Attr-Data field of the Vendor-Specific attribute. The "vsa" data type MUST NOT appear in the contents of any other data type. 2.15. extended The "extended" data type encodes the "Extended Type" format, as given in [RFC6929] Section 2.1. It is used only in the Attr-Data field of an Attribute allocated from the "standard space". It MUST NOT appear @@ -946,25 +990,30 @@ fragmented attribute completely fills the packet. 2.17. evs The "evs" data type encodes an "Extended Vendor-Specific" attribute, as given in [RFC6929] Section 2.4. The "evs" data type is used solely to extend the Vendor Specific space. It MAY appear inside of an "extended" or a "long-extended" data type. It MUST NOT appear in the contents of any other data type. + Where an implementation determines that an attribute of data type + "evs" contains data which does not match the expected format, it + SHOULD treat that attribute as being an "invalid attribute". + Name evs Number + 17 Length Six or more 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 @@ -1057,21 +1105,21 @@ column, which is inserted in between the existing "Description" and "Reference" columns. The new column is named "Data Type". The contents of that column are the name of a data type, corresponding to the attribute in that row, or blank if the attribute type is unassigned. The name of the data type is taken from the RADIUS Data Type registry, defined above. The updated registry follows in CSV format. Value,Description,Data Type,Reference - 1,User-Name,string,[RFC2865] + 1,User-Name,text,[RFC2865] 2,User-Password,string,[RFC2865] 3,CHAP-Password,string,[RFC2865] 4,NAS-IP-Address,ipv4addr,[RFC2865] 5,NAS-Port,integer,[RFC2865] 6,Service-Type,enum,[RFC2865] 7,Framed-Protocol,enum,[RFC2865] 8,Framed-IP-Address,ipv4addr,[RFC2865] 9,Framed-IP-Netmask,ipv4addr,[RFC2865] 10,Framed-Routing,enum,[RFC2865] 11,Filter-Id,text,[RFC2865] @@ -1125,21 +1173,21 @@ 59,User-Priority-Table,string,[RFC4675] 60,CHAP-Challenge,string,[RFC2865] 61,NAS-Port-Type,enum,[RFC2865] 62,Port-Limit,integer,[RFC2865] 63,Login-LAT-Port,text,[RFC2865] 64,Tunnel-Type,enum,[RFC2868] 65,Tunnel-Medium-Type,enum,[RFC2868] 66,Tunnel-Client-Endpoint,text,[RFC2868] 67,Tunnel-Server-Endpoint,text,[RFC2868] 68,Acct-Tunnel-Connection,text,[RFC2867] - 69,Tunnel-Password,text,[RFC2868] + 69,Tunnel-Password,string,[RFC2868] 70,ARAP-Password,string,[RFC2869] 71,ARAP-Features,string,[RFC2869] 72,ARAP-Zone-Access,enum,[RFC2869] 73,ARAP-Security,integer,[RFC2869] 74,ARAP-Security-Data,text,[RFC2869] 75,Password-Retry,integer,[RFC2869] 76,Prompt,enum,[RFC2869] 77,Connect-Info,text,[RFC2869] 78,Configuration-Token,text,[RFC2869] 79,EAP-Message,concat,[RFC2869] @@ -1316,33 +1364,35 @@ A description of the meaning and interpretation of the attribute. Type The Attribute Type code, given in the "dotted number" notation from [RFC6929]. Specifications can often leave this as "TBD", and request that IANA fill in the allocated values. Length - A description of the length of the attribute. For attributes of - variable length, a maximum length SHOULD be given. + attributes of variable length, a maximum length SHOULD be given. + Since the Length may depend on the Type, the definition of Length + may be affected by IANA allocations. Data Type One of the named data types from the RADIUS Data Type registry. Value A description of any attribute-specific limitations on the values carried by the specified data type. If there are no attribute- specific limitations, then the description of this field can be - omitted. + omitted, so long as the Description field is sufficiently + explanatory. Where the values are limited to a subset of the possible range, valid range(s) MUST be defined. For attributes of data type "enum", a list of enumerated values and names MUST be given, as with [RFC2865] Section 5.6. 5. Security Considerations This specification is concerned solely with updates to IANA @@ -1364,22 +1414,22 @@ 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 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. 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 + 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. 7. References 7.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", RFC 2119, March, 1997.