idnits 2.17.1 draft-keiser-afs3-xdr-primitive-types-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- -- The document has an IETF Trust Provisions (28 Dec 2009) Section 6.c(ii) Publication Limitation clause. If this document is intended for submission to the IESG for publication, this constitutes an error. 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 4245 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'Reference' is mentioned on line 147, but not defined -- Looks like a reference, but probably isn't: '6' on line 216 -- Looks like a reference, but probably isn't: '0' on line 236 -- Looks like a reference, but probably isn't: '1' on line 238 -- Looks like a reference, but probably isn't: '2' on line 240 -- Looks like a reference, but probably isn't: '3' on line 242 -- Looks like a reference, but probably isn't: '4' on line 244 -- Looks like a reference, but probably isn't: '5' on line 246 Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 10 comments (--). 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 AFS-3 Rx RPC XDR Primitive Type Definitions 8 draft-keiser-afs3-xdr-primitive-types-01 10 Abstract 12 AFS-3 embeds a set of XDR primitive type definitions, which are 13 referenced throughout the various AFS-3 protocol specifications. 14 This memo defines the mapping between these AFS-3 primitive types, 15 and the underlying XDR primitives. 17 Internet Draft Comments 19 Comments regarding this draft are solicited. Please include the 20 AFS-3 protocol standardization mailing list 21 (afs3-standardization@openafs.org) as a recipient of any comments. 23 AFS-3 Document State 25 This document is in state "draft", as per the document state 26 definitions set forth in [I-D.wilkinson-afs3-standardisation]. 28 Status of this Memo 30 This Internet-Draft is submitted in full conformance with the 31 provisions of BCP 78 and BCP 79. This document may not be modified, 32 and derivative works of it may not be created, and it may not be 33 published except as an Internet-Draft. 35 Internet-Drafts are working documents of the Internet Engineering 36 Task Force (IETF). Note that other groups may also distribute 37 working documents as Internet-Drafts. The list of current Internet- 38 Drafts is at http://datatracker.ietf.org/drafts/current/. 40 Internet-Drafts are draft documents valid for a maximum of six months 41 and may be updated, replaced, or obsoleted by other documents at any 42 time. It is inappropriate to use Internet-Drafts as reference 43 material or to cite them other than as "work in progress." 45 This Internet-Draft will expire on March 14, 2013. 47 Copyright Notice 48 Copyright (c) 2012 IETF Trust and the persons identified as the 49 document authors. All rights reserved. 51 This document is subject to BCP 78 and the IETF Trust's Legal 52 Provisions Relating to IETF Documents 53 (http://trustee.ietf.org/license-info) in effect on the date of 54 publication of this document. Please review these documents 55 carefully, as they describe your rights and restrictions with respect 56 to this document. 58 Table of Contents 60 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 61 1.1. Purpose . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 1.2. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 3 63 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 3. Primitive Integer Types . . . . . . . . . . . . . . . . . . . 4 65 3.1. char . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 66 3.2. unsigned char . . . . . . . . . . . . . . . . . . . . . . 5 67 3.3. short . . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 3.4. unsigned short . . . . . . . . . . . . . . . . . . . . . . 5 69 3.5. 1- and 2-octet integer types . . . . . . . . . . . . . . . 5 70 4. afsUUID . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 71 4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . . . 6 72 4.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . . . 7 73 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 74 6. AFS Assign Numbers Registrar Considerations . . . . . . . . . 8 75 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 76 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 77 8.1. Normative References . . . . . . . . . . . . . . . . . . . 9 78 8.2. Informative References . . . . . . . . . . . . . . . . . . 9 79 Appendix A. Base Type Definitions . . . . . . . . . . . . . . . . 10 80 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 82 1. Introduction 84 AFS-3 [CMU-ITC-88-062] [CMU-ITC-87-068] is a distributed file system 85 that has its origins in the VICE project [CMU-ITC-84-020] 86 [CMU-ITC-85-039] at the Carnegie Mellon University Information 87 Technology Center [CMU-ITC-83-025], a joint venture between CMU and 88 IBM. VICE later became AFS when CMU moved development to a new 89 commercial venture called Transarc Corporation, which later became 90 IBM Pittsburgh Labs. AFS-3 is a suite of un-standardized network 91 protocols based on a remote procedure call (RPC) suite known as Rx 92 [AFS3-RX]. While de jure standards for AFS-3 fail to exist, the 93 various AFS-3 implementations have agreed upon certain de facto 94 standards, largely helped by the existence of an open source fork 95 called OpenAFS that has served the role of reference implementation. 96 In addition to using OpenAFS as a reference, IBM wrote and donated 97 developer documentation that contains somewhat outdated 98 specifications for the Rx protocol and all AFS-3 remote procedure 99 calls, as well as a detailed description of the AFS-3 system 100 architecture. 102 1.1. Purpose 104 The Rx RPC protocol utilizes XDR [RFC4506] as its means of encoding 105 RPC call and response payloads. While XDR provides type definitions 106 for each popular bit-length integer, it does so using relatively 107 ambiguous names (e.g., hyper). To improve readability, the AFS-3 108 RPC-L grammar references custom XDR types that embed the bit length 109 within the type name. This memo standardizes those primitive types, 110 as well as the encoding for the AFS-3 UUID. 112 1.2. Abbreviations 114 AFS - Historically, AFS stood for the Andrew File System; AFS 115 no longer stands for anything 117 DCE - The Distributed Computing Environment 119 LSB - Least-Significant Bit 121 MSB - Most-Significant Bit 123 RPC - Remote Procedure Call 125 RPC-L - Rx RPC Interface Definition Language (fork of ONC RPC 126 [RFC5531] .x file format) 128 Rx - The Remote Procedure Call mechanism utilized by AFS-3 129 [AFS3-RX] 131 UUID - Universally Unique IDentifier 133 XDR - eXternal Data Representation [RFC4506] 135 2. Conventions 137 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 138 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 139 document are to be interpreted as described in RFC 2119 [RFC2119]. 141 3. Primitive Integer Types 143 AFS-3 defines a number of special types which are direct mappings 144 onto existing XDR types. Thus, these types are essentially XDR 145 typedefs: 147 AFS-3 type name -> XDR primitive type [Reference] 148 --------------- ------------------ ----------- 149 char int RFC 4506 Section 4.1 150 unsigned char unsigned int RFC 4506 Section 4.2 151 afs_int8 int RFC 4506 Section 4.1 152 afs_uint8 unsigned int RFC 4506 Section 4.2 153 short int RFC 4506 Section 4.1 154 unsigned short unsigned int RFC 4506 Section 4.2 155 afs_int16 int RFC 4506 Section 4.1 156 afs_uint16 unsigned int RFC 4506 Section 4.2 157 afs_int32 int RFC 4506 Section 4.1 158 afs_uint32 unsigned int RFC 4506 Section 4.2 159 afs_int64 hyper RFC 4506 Section 4.5 160 afs_uint64 unsigned hyper RFC 4506 Section 4.5 162 AFS-3 common typedefs 164 Figure 1 166 3.1. char 168 This type is considered deprecated; future protocol specifications 169 should reference the "afs_int8" type instead. 171 3.2. unsigned char 173 This type is considered deprecated; future protocol specifications 174 should reference the "afs_uint8" type instead. 176 3.3. short 178 This type is considered deprecated; future protocol specifications 179 should reference the "afs_int16" type instead. 181 3.4. unsigned short 183 This type is considered deprecated; future protocol specifications 184 should reference the "afs_uint16" type instead. 186 3.5. 1- and 2-octet integer types 188 Please note that XDR uses a 4-octet alignment, and thus these 1- and 189 2-octet types will take 4 octets on the wire. Consequently, this is 190 merely a way of defining data structures that have an optimized in- 191 memory footprint, without imbuing any wire-encoding advantage. 193 4. afsUUID 195 AFS-3, being closely related to DCE, relies heavily upon a UUID type. 196 The AFS-3 UUID type is identical to the DCE-variant, version 1 UUID 197 type (see Appendix A of [DCE-RPC]). The C data structure definition 198 for such a UUID is as follows: 200 /* 201 * Copyright 2000, International Business Machines Corporation 202 * and others. All Rights Reserved. 203 * 204 * This software has been released under the terms of the IBM 205 * Public License. For details, see the LICENSE file in the 206 * top-level source directory or online at 207 * http://www.openafs.org/dl/license10.html 208 */ 210 struct afsUUID { 211 afs_uint32 time_low; 212 afs_uint16 time_mid; 213 afs_uint16 time_hi_and_version; 214 char clock_seq_hi_and_reserved; 215 char clock_seq_low; 216 char node[6]; 217 }; 218 typedef struct afsUUID afsUUID; 220 An afsUUID type is XDR encoded on the wire as follows: 222 (MSB) (LSB) 223 0 1 2 3 224 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 225 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 226 | time_low | 227 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 228 | 0 | time_mid | 229 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 230 | 0 | time_hi_and_version | 231 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 232 | {3} | {1} | 233 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 234 | {3} | {2} | 235 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 236 | {3} | node[0] | 237 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 238 | {3} | node[1] | 239 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 240 | {3} | node[2] | 241 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 242 | {3} | node[3] | 243 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 244 | {3} | node[4] | 245 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 246 | {3} | node[5] | 247 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 249 {1} clock_seq_hi_and_reserved 250 {2} clock_seq_low 251 {3} sign extended padding: 0, or 0xffffff depending on value 252 of MSB in field to be sign-extended and padded 254 afsUUID XDR encoding 256 4.1. Encoding 258 XDR encoding an "afsUUID" type SHALL involve the following sequence 259 of operations: 261 1. Encode "time_low" field as an XDR unsigned integer (afs_uint32) 263 2. Encode "time_mid" field as an XDR unsigned integer 264 3. Encode "time_hi_and_version" field as an XDR unsigned integer 266 4. Encode "clock_seq_hi_and_reserved" field as an XDR signed 267 integer 269 5. Encode "clock_seq_low" field as an XDR signed integer 271 6. Encode "node[0]" field as an XDR signed integer 273 7. Encode "node[1]" field as an XDR signed integer 275 8. Encode "node[2]" field as an XDR signed integer 277 9. Encode "node[3]" field as an XDR signed integer 279 10. Encode "node[4]" field as an XDR signed integer 281 11. Encode "node[5]" field as an XDR signed integer 283 Many of the fields which are encoded in this data structure are 284 smaller than four octets. In order to XDR encode these fields, they 285 must first be resized. Since many of these fields are signed, this 286 involves sign extension. This process depends upon the machine 287 architecture. Virtually all machines in existence today utilize 2s- 288 complement integer arithmetic, where this process merely involves 289 padding with zeros if the MSB is zero or ones if the MSB is one. 291 4.2. Decoding 293 XDR decoding an "afsUUID" type SHALL involve the following sequence 294 of operations: 296 1. Decode an XDR unsigned integer into the "time_low" field 298 2. Decode an XDR unsigned integer. If the integer is greater than 299 65535, the decoding SHALL fail. Copy the least-significant 16 300 bits into the "time_mid" field. 302 3. Decode an XDR unsigned integer. If the integer is greater than 303 65535, the decoding SHALL fail. Copy the least-significant 16 304 bits into the "time_hi_and_version" field. 306 4. Decode an XDR signed integer. If the integer is greater than 307 32767, or less than -32768, the decoding SHALL fail. Copy the 308 least-significant 16 bits into the "clock_seq_hi_and_reserved" 309 field. 311 5. Decode an XDR signed integer. If the integer is greater than 312 32767, or less than -32768, the decoding SHALL fail. Copy the 313 least-significant 16 bits into the "clock_seq_low" field. 315 6. Decode an XDR signed integer. If the integer is greater than 316 127, or less than -128, the decoding SHALL fail. Copy the 317 least-significant 8 bits into the "node[0]" field. 319 7. Decode an XDR signed integer. If the integer is greater than 320 127, or less than -128, the decoding SHALL fail. Copy the 321 least-significant 8 bits into the "node[1]" field. 323 8. Decode an XDR signed integer. If the integer is greater than 324 127, or less than -128, the decoding SHALL fail. Copy the 325 least-significant 8 bits into the "node[2]" field. 327 9. Decode an XDR signed integer. If the integer is greater than 328 127, or less than -128, the decoding SHALL fail. Copy the 329 least-significant 8 bits into the "node[3]" field. 331 10. Decode an XDR signed integer. If the integer is greater than 332 127, or less than -128, the decoding SHALL fail. Copy the 333 least-significant 8 bits into the "node[4]" field. 335 11. Decode an XDR signed integer. If the integer is greater than 336 127, or less than -128, the decoding SHALL fail. Copy the 337 least-significant 8 bits into the "node[5]" field. 339 5. IANA Considerations 341 This memo includes no request to IANA. 343 6. AFS Assign Numbers Registrar Considerations 345 This memo includes no request to the AFS Assigned Numbers Registrar. 347 7. Security Considerations 349 This document merely describes various AFS-3 XDR types. Any protocol 350 specification which uses these primitives types must ensure the 351 security of the resulting XDR data streams, e.g., via prescription of 352 a suitable Rx RPC security class. 354 8. References 355 8.1. Normative References 357 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 358 Requirement Levels", BCP 14, RFC 2119, March 1997. 360 [RFC4506] Eisler, M., "XDR: External Data Representation Standard", 361 STD 67, RFC 4506, May 2006. 363 8.2. Informative References 365 [AFS3-RX] Zayas, E., "AFS-3 Programmer's Reference: Specification 366 for the Rx Remote Procedure Call Facility", Transarc Corp. 367 Tech. Rep. FS-00-D164, August 1991. 369 [CMU-ITC-83-025] 370 Morris, J., Van Houweling, D., and K. Slack, "The 371 Information Technology Center", CMU ITC Tech. Rep. CMU- 372 ITC-83-025, 1983. 374 [CMU-ITC-84-020] 375 West, M., "VICE File System Services", CMU ITC Tech. 376 Rep. CMU-ITC-84-020, August 1984. 378 [CMU-ITC-85-039] 379 Satyanarayanan, M., Howard, J., Nichols, D., Sidebotham, 380 R., Spector, A., and M. West, "The ITC Distributed File 381 System: Principles and Design", Proc. 10th ACM Symp. 382 Operating Sys. Princ. Vol. 19, No. 5, December 1985. 384 [CMU-ITC-87-068] 385 Howard, J., Kazar, M., Menees, S., Nichols, D., 386 Satyanarayanan, M., Sidebotham, R., and M. West, "Scale 387 and Performance in a Distributed File System", ACM Trans. 388 Comp. Sys. Vol. 6, No. 1, pp. 51-81, February 1988. 390 [CMU-ITC-88-062] 391 Howard, J., "An Overview of the Andrew File System"", 392 Proc. 1988 USENIX Winter Tech. Conf. pp. 23-26, 393 February 1988. 395 [DCE-RPC] The Open Group, "CAE Specification, DCE 1.1: Remote 396 Procedure Call", CAE C706, August 1997. 398 [I-D.wilkinson-afs3-standardisation] 399 Wilkinson, S., "Options for AFS Standardisation", 400 draft-wilkinson-afs3-standardisation-00 (work in 401 progress), June 2010. 403 [RFC5531] Thurlow, R., "RPC: Remote Procedure Call Protocol 404 Specification Version 2", RFC 5531, May 2009. 406 Appendix A. Base Type Definitions 408 typedef afs_int8 int; 409 typedef afs_uint8 unsigned int; 410 typedef afs_int16 int; 411 typedef afs_uint16 unsigned int; 412 typedef afs_int32 int; 413 typedef afs_uint32 unsigned int; 414 typedef afs_int64 hyper; 415 typedef afs_uint64 unsigned hyper; 417 Authors' Addresses 419 Thomas Keiser 420 Sine Nomine Associates 421 43596 Blacksmith Square 422 Ashburn, VA 20147 423 USA 425 Email: tkeiser@gmail.com 427 Andrew Deason (editor) 428 Sine Nomine Associates 429 43596 Blacksmith Square 430 Ashburn, Virginia 20147-4606 431 USA 433 Phone: +1 703 723 6673 434 Email: adeason@sinenomine.net