idnits 2.17.1 draft-keiser-afs3-xdr-union-06.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([I-D.wilkinson-afs3-standardisation]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 10, 2012) is 4236 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 N/A T. Keiser 3 Internet-Draft A. Deason, Ed. 4 Intended status: Informational Sine Nomine 5 Expires: March 14, 2013 September 10, 2012 7 Extensible XDR Discriminated Union Primitive Type 8 draft-keiser-afs3-xdr-union-06 10 Abstract 12 AFS-3 relies upon XDR to carry Rx RPC call payloads. XDR 13 discriminated unions are ill-suited to cases where the protocol needs 14 to evolve without inventing new RPCs, i.e., unknown discriminant 15 values cause the entire XDR payload to fail the decoding step. While 16 this can be circumvented through the use of opaque payloads (and 17 recursive XDR invocations), such solutions are inelegant and 18 difficult to implement. This memo defines a new XDR primitive type, 19 "ext-union", which is derived from the XDR discriminated union 20 primitive type, but with two key variations: 1) each leg contains a 21 length field, and 2) no default leg is supported. 23 Internet Draft Comments 25 Comments regarding this draft are solicited. Please include the 26 AFS-3 protocol standardization mailing list 27 (afs3-standardization@openafs.org) as a recipient of any comments. 29 AFS-3 Document State 31 This document is in state "draft", as per the document state 32 definitions set forth in [I-D.wilkinson-afs3-standardisation]. 34 Status of this Memo 36 This Internet-Draft is submitted in full conformance with the 37 provisions of BCP 78 and BCP 79. 39 Internet-Drafts are working documents of the Internet Engineering 40 Task Force (IETF). Note that other groups may also distribute 41 working documents as Internet-Drafts. The list of current Internet- 42 Drafts is at http://datatracker.ietf.org/drafts/current/. 44 Internet-Drafts are draft documents valid for a maximum of six months 45 and may be updated, replaced, or obsoleted by other documents at any 46 time. It is inappropriate to use Internet-Drafts as reference 47 material or to cite them other than as "work in progress." 48 This Internet-Draft will expire on March 14, 2013. 50 Copyright Notice 52 Copyright (c) 2012 IETF Trust and the persons identified as the 53 document authors. All rights reserved. 55 This document is subject to BCP 78 and the IETF Trust's Legal 56 Provisions Relating to IETF Documents 57 (http://trustee.ietf.org/license-info) in effect on the date of 58 publication of this document. Please review these documents 59 carefully, as they describe your rights and restrictions with respect 60 to this document. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 65 1.1. Use Case . . . . . . . . . . . . . . . . . . . . . . . . . 3 66 1.2. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 3 67 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 68 3. Extensible Discriminated Union . . . . . . . . . . . . . . . . 4 69 3.1. Extensible Union Type . . . . . . . . . . . . . . . . . . 4 70 3.2. RPC-L Changes . . . . . . . . . . . . . . . . . . . . . . 6 71 3.3. Encoding . . . . . . . . . . . . . . . . . . . . . . . . . 7 72 3.4. Decoding . . . . . . . . . . . . . . . . . . . . . . . . . 7 73 3.4.1. Error Handling . . . . . . . . . . . . . . . . . . . . 8 74 4. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9 75 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 76 6. AFS Assigned Numbers Registrar Considerations . . . . . . . . 9 77 7. Security Considerations . . . . . . . . . . . . . . . . . . . 9 78 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 79 8.1. Normative References . . . . . . . . . . . . . . . . . . . 10 80 8.2. Informative References . . . . . . . . . . . . . . . . . . 10 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 83 1. Introduction 85 AFS-3 [CMU-ITC-88-062] [CMU-ITC-87-068] is a distributed file system 86 that has its origins in the VICE project [CMU-ITC-84-020] 87 [CMU-ITC-85-039] at the Carnegie Mellon University Information 88 Technology Center [CMU-ITC-83-025], a joint venture between CMU and 89 IBM. VICE later became AFS when CMU moved development to a new 90 commercial venture called Transarc Corporation, which later became 91 IBM Pittsburgh Labs. AFS-3 is a suite of un-standardized network 92 protocols based on a remote procedure call (RPC) suite known as Rx 93 [AFS3-RX]. While de jure standards for AFS-3 fail to exist, the 94 various AFS-3 implementations have agreed upon certain de facto 95 standards, largely helped by the existence of an open source fork 96 called OpenAFS that has served the role of reference implementation. 97 In addition to using OpenAFS as a reference, IBM wrote and donated 98 developer documentation that contains somewhat outdated 99 specifications for the Rx protocol and all AFS-3 remote procedure 100 calls, as well as a detailed description of the AFS-3 system 101 architecture. 103 The Rx RPC protocol utilizes XDR [RFC4506] as its means of encoding 104 RPC call and response payloads. XDR provides a discriminated union 105 type. However, the semantics of the discriminated union base type do 106 not lend themselves to evolution of the discriminant namespace: 107 introduction of new discriminants--when there is no default leg-- 108 cause the remainder of the XDR octet stream to be un-parseable (due 109 to the lack of a length field in the encoding) by older peers. This 110 memo introduces a new XDR primitive type that is identical to the XDR 111 discriminated union, except that: 113 1. each leg contains a length field, and 115 2. the default leg is disallowed. 117 1.1. Use Case 119 Given that this design doubles the overhead from 4 to 8 octets 120 (relative to the XDR discriminated union primitive type), it is ill- 121 suited for use with small implied legs. Within the AFS-3 protocol 122 suite, the primary use case for the extensible union type is to wrap 123 large data structures, rather than small primitive types. 125 1.2. Abbreviations 126 AFS - Historically, AFS stood for the Andrew File System; AFS 127 no longer stands for anything 129 RPC - Remote Procedure Call 131 RPC-L - Rx RPC Interface Definition Language (fork of ONC RPC 132 [RFC5531] .x file format) 134 Rx - The Remote Procedure Call mechanism utilized by AFS-3 135 [AFS3-RX] 137 XDR - eXternal Data Representation [RFC4506] 139 2. Conventions 141 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 142 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 143 document are to be interpreted as described in RFC 2119 [RFC2119]. 145 3. Extensible Discriminated Union 147 The extensible discriminated union will contain a length field in 148 every leg so that decoding peers can compute the offset of the next 149 object in the XDR octet stream, regardless of whether the 150 discriminant is recognized. For small legs, this will result in 151 significant encoding inefficiency, but it is necessary to permit the 152 union to evolve over time (without peers failing to decode the entire 153 XDR octet stream). 155 3.1. Extensible Union Type 157 The definition of the extensible discriminated union is derived from 158 the XDR union defined in section 4.15 of the XDR specification 159 [RFC4506]. Unlike XDR discriminated unions, the XDR types mapped to 160 each arm of the union need not be defined a priori. Instead, the 161 length of the arm is always included in the wire encoding along with 162 the discriminant value, thus permitting the decoder to continue 163 decoding past an unknown discriminant in an XDR octet stream. 165 How undefined discriminants are handled by the decoder is 166 deliberately left unspecified by this document. Rather, this memo 167 merely specifies which error conditions must be flagged to the caller 168 (see Section 3.4.1). The error handling semantics--for both length 169 mismatches and unknown discriminants--are left up to the definition 170 of any type built upon the ext-union primitive type. While this 171 lends significant flexibility to the design, it also permits XDR 172 decoding to continue when the expected implied arm length doesn't 173 match the length on the wire. It is RECOMMENDED that implementations 174 fail to decode the entire XDR stream when such a length mismatch is 175 encountered, as such a length mismatch is indicative of either: 177 1. a significant divergence in RPC-L definitions across the peers, 178 or 180 2. an undetected bit error in the XDR octet stream. 182 Extensible discriminated unions are defined in RPC-L as follows: 184 ext-union [ max-unknown-leg-length=X ] 185 switch (discriminant-definition) { 186 case discriminant-value-A: 187 arm-declaration-A; 188 case discriminant-value-B: 189 arm-declaration-B; 190 ... 191 } identifier; 193 Figure 1 195 Because the discriminant namespace of an extensible union must be 196 capable of evolving over time, it is not possible to support a 197 default leg. 199 The max-unknown-leg-length optional parameter specifies the maximum 200 permissible leg length for any union leg whose discriminant value is 201 not known to the decoder. This is necessary to limit the scope of 202 denial of service attacks: by permitting the decoder to detect 203 inordinately large payloads--after only receiving the first few 204 octets of the extensible union. 206 The extensible discriminated union is encoded on the wire as: a 207 4-octet discriminant, followed by a 4-octet arm length, and finally 208 the variable-length implied arm. The arm length field SHALL count 209 the length of the implied arm in octets, and only the implied arm. 210 In other words, the 8 octets occupied by the discriminant and arm 211 length fields SHALL NOT be counted as part of the arm length value. 213 0 1 2 3 214 +---+---+---+---+---+---+---+---+---+---+---+---+ 215 | discriminant | arm length | implied arm | 216 +---+---+---+---+---+---+---+---+---+---+---+---+ 217 |<---4 octets-->|<---4 octets-->| 219 Figure 2 221 It should be noted that this design makes it convenient to implement 222 extensible discriminated unions on top of existing XDR primitive 223 types. Thus, in terms of the existing XDR primitives [RFC4506], we 224 can describe an extensible discriminated union as follows: 226 struct ext_union { 227 unsigned int discriminant; 228 opaque implied_leg<>; 229 }; 231 Figure 3 233 3.2. RPC-L Changes 235 In order to implement the above, the XDR grammar, as specified in 236 Section 6.3 of [RFC4506], will need to be modified in the following 237 ways: 239 o "type-specifier" will require a new production rule mapping to 240 "ext-union-type-spec", and 242 o an "ext-union-type-spec" production rule will need to be defined. 244 The "type-specifier" grammar will now include a new production rule 245 for "ext-union-type-spec": 247 type-specifier: 248 [ "unsigned" ] "int" 249 | [ "unsigned" ] "hyper" 250 | "float" 251 | "double" 252 | "quadruple" 253 | "bool" 254 | enum-type-spec 255 | struct-type-spec 256 | union-type-spec 257 | identifier 258 | ext-union-type-spec 260 Figure 4 262 The new "ext-union-type-spec" production rule, and the production 263 rule for its nonterminal symbol dependency "ext-union-body", are 264 defined as follows: 266 ext-union-type-spec: 267 "ext-union" ext-union-body 268 | "ext-union" ext-union-options ext-union-body 270 ext-union-options: 271 "[" ext-union-options-body "]" 273 ext-union-options-body: 274 ext-union-option 275 | ext-union-option "," ext-union-options-body 277 ext-union-option: 278 "max-unknown-leg-length" "=" value 280 ext-union-body: 281 "switch" "(" declaration ")" "{" 282 case-spec 283 case-spec * 284 "}" 286 Figure 5 288 3.3. Encoding 290 It is RECOMMENDED that encoding of an AFS-3 extensible union proceed 291 using the following algorithm: 293 1. encode an XDR unsigned 32-bit integer (see Section 4.2 of 294 [RFC4506]) containing the discrimant, 296 2. XDR encode into temporary storage the implied leg (according to 297 the type definition of the type specified for this discriminant 298 value in the ext-union definition), and 300 3. encode the implied leg using the XDR variable-length opaque 301 specification (see Section 4.10 of [RFC4506]). 303 3.4. Decoding 305 It is RECOMMENDED that decoding of an AFS-3 extensible union proceed 306 using the following algorithm: 308 1. XDR decode the 32-bit unsigned integer containing the 309 discriminant; 311 2. XDR decode the variable-length opaque blob into temporary 312 storage; 314 3. If this is a known discriminant: 316 1. XDR decode the implied leg payload using the appropriate 317 decoder for the discriminant value; 319 2. Compare the length of the decoded XDR payload against the 320 previously-decoded extensible union implied leg length. If 321 the lengths do not match, then mark the union as failed to 322 decode due to a length mismatch; 324 4. However, if this is an unknown discriminant, then mark the union 325 as failed to decode due to an unknown discriminant; 327 5. XDR decoding continues at the current offset plus the length of 328 the previously-decoded XDR variable-length opaque. 330 3.4.1. Error Handling 332 While the specific decoding algorithm used is left up to the 333 implementor, error handling MUST be implemented as described in this 334 section. 336 Unknown Discriminant: 338 When a decoder encounters an unknown discriminant, it MUST mark 339 the discriminant as unknown, and SHOULD proceed to decoding the 340 next element in the XDR stream by seeking past the length and 341 implied leg fields. 343 Unexpected Length for Discriminant: 345 When a decoder encounters a length field that doesn't agree with 346 the length expected for this discriminant, it MUST mark the 347 discriminant as failed to decode due to a length mismatch, and 348 SHOULD fail to decode the rest of the XDR octet stream. 350 Excessively Long Payload: 352 When the following conditions are satisfied: 354 1. the max-unknown-leg-length value is specified in the 355 extensible union type definition, and 357 2. the discriminant value is unknown, and 359 3. the implied leg length exceeds the max-unknown-leg-length 360 specified in the type definition, 362 then the decoder MUST mark the discriminant as failed to decode 363 due to excessive length, and SHOULD fail to decode the rest of 364 the XDR octet stream. In addition, an implementation MAY choose 365 to mark a discriminant as failed to decode--and MAY fail to 366 decode the rest of the XDR octet stream--when a known implied 367 leg's length exceeds the max-unknown-leg-length in the extensible 368 union type specification. 370 4. Acknowledgements 372 The author would like to thank Jeffrey Hutzelman for proposing 373 standardization of a new XDR primitive type; and Matt Benjamin, 374 Derrick Brashear, Andrew Deason, Steven Jenkins, Michael Meffie, Mark 375 Vitale, and Simon Wilkinson for helping to refine the design of this 376 extensible union type. Finally, the author would like to thank the 377 attendees of the 2011 Pittsburgh AFS Hackathon for their review and 378 comments regarding the -01 draft. 380 5. IANA Considerations 382 This memo includes no request to IANA. 384 6. AFS Assigned Numbers Registrar Considerations 386 This memo includes no request to the AFS Assigned Numbers Registrar. 388 7. Security Considerations 390 Users of this extensible type should understand that any Rx XDR 391 payload is only as secure as the security class bound to the Rx 392 connection in question. This document merely standardizes a 393 primitive type; it is up to the authors of standards defining new 394 types (upon the "ext-union" primitive type) to ensure that the 395 contents of their types are only marshalled over sufficiently-secure 396 security classes. 398 Decoders should take special care when encountering unexpected 399 implied arm lengths. This could be indicative of serious errors, 400 such as octet stream bit errors that were undetected by lower-layer 401 checksums. At the very least, this error condition implies that the 402 peers do not agree upon their ext-union type-to-discriminant 403 mappings. It is RECOMMENDED that decoders treat this as a hard error 404 and fail to decode the remainder of the XDR octet stream. 406 8. References 408 8.1. Normative References 410 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 411 Requirement Levels", BCP 14, RFC 2119, March 1997. 413 [RFC4506] Eisler, M., "XDR: External Data Representation Standard", 414 STD 67, RFC 4506, May 2006. 416 8.2. Informative References 418 [AFS3-RX] Zayas, E., "AFS-3 Programmer's Reference: Specification 419 for the Rx Remote Procedure Call Facility", Transarc Corp. 420 Tech. Rep. FS-00-D164, August 1991. 422 [CMU-ITC-83-025] 423 Morris, J., Van Houweling, D., and K. Slack, "The 424 Information Technology Center", CMU ITC Tech. Rep. CMU- 425 ITC-83-025, 1983. 427 [CMU-ITC-84-020] 428 West, M., "VICE File System Services", CMU ITC Tech. 429 Rep. CMU-ITC-84-020, August 1984. 431 [CMU-ITC-85-039] 432 Satyanarayanan, M., Howard, J., Nichols, D., Sidebotham, 433 R., Spector, A., and M. West, "The ITC Distributed File 434 System: Principles and Design", Proc. 10th ACM Symp. 435 Operating Sys. Princ. Vol. 19, No. 5, December 1985. 437 [CMU-ITC-87-068] 438 Howard, J., Kazar, M., Menees, S., Nichols, D., 439 Satyanarayanan, M., Sidebotham, R., and M. West, "Scale 440 and Performance in a Distributed File System", ACM Trans. 441 Comp. Sys. Vol. 6, No. 1, pp. 51-81, February 1988. 443 [CMU-ITC-88-062] 444 Howard, J., "An Overview of the Andrew File System"", 445 Proc. 1988 USENIX Winter Tech. Conf. pp. 23-26, 446 February 1988. 448 [I-D.wilkinson-afs3-standardisation] 449 Wilkinson, S., "Options for AFS Standardisation", 450 draft-wilkinson-afs3-standardisation-00 (work in 451 progress), June 2010. 453 [RFC5531] Thurlow, R., "RPC: Remote Procedure Call Protocol 454 Specification Version 2", RFC 5531, May 2009. 456 Authors' Addresses 458 Thomas Keiser 459 Sine Nomine Associates 460 43596 Blacksmith Square 461 Ashburn, VA 20147 462 USA 464 Email: tkeiser@gmail.com 466 Andrew Deason (editor) 467 Sine Nomine Associates 468 43596 Blacksmith Square 469 Ashburn, Virginia 20147-4606 470 USA 472 Phone: +1 703 723 6673 473 Email: adeason@sinenomine.net