Network Working Group T. Keiser Internet-Draft Sine Nomine Intended status: Informational June 2, 2011 Expires: December 4, 2011 AFS-3 Rx RPC XDR Primitive Type Definitions draft-keiser-afs3-xdr-primitive-types-00 Abstract AFS-3 embeds a set of XDR primitive type definitions, which are referenced throughout the various AFS-3 protocol specifications. This memo defines the mapping between these AFS-3 primitive types, and the underlying XDR primitives. Internet Draft Comments Comments regarding this draft are solicited. Please include the AFS-3 protocol standardization mailing list (afs3-standardization@openafs.org) as a recipient of any comments. Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months 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." This Internet-Draft will expire on December 4, 2011. Copyright Notice 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) in effect on the date of publication of this document. Please review these documents Keiser Expires December 4, 2011 [Page 1] Internet-Draft AFS-3 XDR Primitive Types June 2011 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 described in the Simplified BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Primitive Integer Types . . . . . . . . . . . . . . . . . . . 4 3.1. char . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.2. unsigned char . . . . . . . . . . . . . . . . . . . . . . 4 3.3. short . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.4. unsigned short . . . . . . . . . . . . . . . . . . . . . . 5 3.5. 1- and 2-octet integer types . . . . . . . . . . . . . . . 5 4. afsUUID . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 4.1. Encoding . . . . . . . . . . . . . . . . . . . . . . . . . 6 4.2. Decoding . . . . . . . . . . . . . . . . . . . . . . . . . 7 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 6. AFS Assign Numbers Registrar Considerations . . . . . . . . . 8 7. Security Considerations . . . . . . . . . . . . . . . . . . . 8 8. References . . . . . . . . . . . . . . . . . . . . . . . . . . 8 8.1. Normative References . . . . . . . . . . . . . . . . . . . 8 8.2. Informative References . . . . . . . . . . . . . . . . . . 9 Appendix A. Base Type Definitions . . . . . . . . . . . . . . . . 9 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10 Keiser Expires December 4, 2011 [Page 2] Internet-Draft AFS-3 XDR Primitive Types June 2011 1. Introduction AFS-3 [AFS1] [AFS2] is a distributed file system that has its origins in the VICE project [CMU-ITC-84-020] [VICE1] at the Carnegie Mellon University Information Technology Center [CMU-ITC-83-025], a joint venture between CMU and IBM. VICE later became AFS when CMU moved development to a new commercial venture called Transarc Corporation, which later became IBM Pittsburgh Labs. AFS-3 is a suite of un- standardized network protocols based on a remote procedure call (RPC) suite known as Rx [AFS3-RX]. While de jure standards for AFS-3 fail to exist, the various AFS-3 implementations have agreed upon certain de facto standards, largely helped by the existence of an open source fork called OpenAFS that has served the role of reference implementation. In addition to using OpenAFS as a reference, IBM wrote and donated developer documentation that contains somewhat outdated specifications for the Rx protocol and all AFS-3 remote procedure calls, as well as a detailed description of the AFS-3 system architecture. The Rx RPC protocol utilizes XDR [RFC4506] as its means of encoding RPC call and response payloads. While XDR provides type definitions for each popular bit-length integer, it does so using relatively ambiguous names (e.g., hyper). To improve readability, AFS-3 standards reference custom XDR types that embed the bit length within the type name. This memo standardizes those primitive types, as well as the encoding for the AFS-3 UUID. 1.1. Abbreviations AFS - Historically, AFS stood for the Andrew File System; AFS no longer stands for anything DCE - The Distributed Computing Environment LSB - Least-Significant Bit MSB - Most-Significant Bit RPC - Remote Procedure Call Rx - The Remote Procedure Call mechanism utilized by AFS-3 UUID - Universally Unique IDentifier XDR - eXternal Data Representation Keiser Expires December 4, 2011 [Page 3] Internet-Draft AFS-3 XDR Primitive Types June 2011 2. Conventions 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 RFC 2119 [RFC2119]. 3. Primitive Integer Types AFS-3 defines a number of special types which are direct mappings onto existing XDR types. Thus, these types are essentially XDR typedefs: AFS-3 type name -> XDR primitive type [Reference] --------------- ------------------ ----------- char int RFC 4506 Section 4.1 unsigned char unsigned int RFC 4506 Section 4.2 afs_int8 int RFC 4506 Section 4.1 afs_uint8 unsigned int RFC 4506 Section 4.2 short int RFC 4506 Section 4.1 unsigned short unsigned int RFC 4506 Section 4.2 afs_int16 int RFC 4506 Section 4.1 afs_uint16 unsigned int RFC 4506 Section 4.2 afs_int32 int RFC 4506 Section 4.1 afs_uint32 unsigned int RFC 4506 Section 4.2 afs_int64 hyper RFC 4506 Section 4.5 afs_uint64 unsigned hyper RFC 4506 Section 4.5 AFS-3 common typedefs Figure 1 3.1. char This type is considered deprecated; future protocol specifications should reference the "afs_int8" type instead. 3.2. unsigned char This type is considered deprecated; future protocol specifications should reference the "afs_uint8" type instead. 3.3. short This type is considered deprecated; future protocol specifications should reference the "afs_int16" type instead. Keiser Expires December 4, 2011 [Page 4] Internet-Draft AFS-3 XDR Primitive Types June 2011 3.4. unsigned short This type is considered deprecated; future protocol specifications should reference the "afs_uint16" type instead. 3.5. 1- and 2-octet integer types Please note that XDR uses a 4-octet alignment, and thus these 1- and 2-octet types will take 4 octets on the wire. Consequently, this is merely a way of defining data structures that have an optimized in- memory footprint, without imbuing any wire-encoding advantage. 4. afsUUID AFS-3, being closely related to DCE, relies heavily upon a UUID type. The AFS-3 UUID type is identical to the DCE-variant, version 1 UUID type (see Appendix A of [dce_rpc]). The C data structure definition for such a UUID is as follows: struct afsUUID { afs_uint32 time_low; afs_uint16 time_mid; afs_uint16 time_hi_and_version; char clock_seq_hi_and_reserved; char clock_seq_low; char node[6]; }; typedef struct afsUUID afsUUID; An afsUUID type is XDR encoded on the wire as follows: Keiser Expires December 4, 2011 [Page 5] Internet-Draft AFS-3 XDR Primitive Types June 2011 (MSB) (LSB) 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_low | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0 | time_mid | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0 | time_hi_and_version | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | {3} | {1} | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | {3} | {2} | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | {3} | node[0] | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | {3} | node[1] | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | {3} | node[2] | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | {3} | node[3] | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | {3} | node[4] | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | {3} | node[5] | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ {1} clock_seq_hi_and_reserved {2} clock_seq_low {3} sign extended padding: 0, or 0xffffff depending on value of MSB in field to be sign-extended and padded afsUUID XDR encoding 4.1. Encoding XDR encoding an "afsUUID" type SHALL involve the following sequence of operations: 1. Encode "time_low" field as an XDR unsigned integer (afs_uint32) 2. Encode "time_mid" field as an XDR unsigned integer 3. Encode "time_hi_and_version" field as an XDR unsigned integer 4. Encode "clock_seq_hi_and_reserved" field as an XDR signed integer Keiser Expires December 4, 2011 [Page 6] Internet-Draft AFS-3 XDR Primitive Types June 2011 5. Encode "clock_seq_low" field as an XDR signed integer 6. Encode "node[0]" field as an XDR signed integer 7. Encode "node[1]" field as an XDR signed integer 8. Encode "node[2]" field as an XDR signed integer 9. Encode "node[3]" field as an XDR signed integer 10. Encode "node[4]" field as an XDR signed integer 11. Encode "node[5]" field as an XDR signed integer Many of the fields which are encoded in this data structure are smaller than four octets. In order to XDR encode these fields, they must first be resized. Since many of these fields are signed, this involves sign extension. This process depends upon the machine architecture. Virtually all machines in existence today utilize 2s- complement integer arithmetic, where this process merely involves padding with zeros if the MSB is zero or ones if the MSB is one. 4.2. Decoding XDR decoding an "afsUUID" type SHALL involve the following sequence of operations: 1. Decode an XDR unsigned integer into the "time_low" field 2. Decode an XDR unsigned integer. If the integer is greater than 65535, the decoding SHALL fail. Copy the least-significant 16 bits into the "time_mid" field. 3. Decode an XDR unsigned integer. If the integer is greater than 65535, the decoding SHALL fail. Copy the least-significant 16 bits into the "time_hi_and_version" field. 4. Decode an XDR signed integer. If the integer is greater than 32767, or less than -32768, the decoding SHALL fail. Copy the least-significant 16 bits into the "clock_seq_hi_and_reserved" field. 5. Decode an XDR signed integer. If the integer is greater than 32767, or less than -32768, the decoding SHALL fail. Copy the least-significant 16 bits into the "clock_seq_low" field. 6. Decode an XDR signed integer. If the integer is greater than 127, or less than -128, the decoding SHALL fail. Copy the Keiser Expires December 4, 2011 [Page 7] Internet-Draft AFS-3 XDR Primitive Types June 2011 least-significant 8 bits into the "node[0]" field. 7. Decode an XDR signed integer. If the integer is greater than 127, or less than -128, the decoding SHALL fail. Copy the least-significant 8 bits into the "node[1]" field. 8. Decode an XDR signed integer. If the integer is greater than 127, or less than -128, the decoding SHALL fail. Copy the least-significant 8 bits into the "node[2]" field. 9. Decode an XDR signed integer. If the integer is greater than 127, or less than -128, the decoding SHALL fail. Copy the least-significant 8 bits into the "node[3]" field. 10. Decode an XDR signed integer. If the integer is greater than 127, or less than -128, the decoding SHALL fail. Copy the least-significant 8 bits into the "node[4]" field. 11. Decode an XDR signed integer. If the integer is greater than 127, or less than -128, the decoding SHALL fail. Copy the least-significant 8 bits into the "node[5]" field. 5. IANA Considerations This memo includes no request to IANA. 6. AFS Assign Numbers Registrar Considerations This memo includes no request to the AFS Assigned Numbers Registrar. 7. Security Considerations This document merely describes various AFS-3 XDR types. Any protocol specification which uses these primitives types must ensure the security of the resulting XDR data streams, e.g., via prescription of a suitable Rx RPC security class. 8. References 8.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. Keiser Expires December 4, 2011 [Page 8] Internet-Draft AFS-3 XDR Primitive Types June 2011 [RFC4506] Eisler, M., "XDR: External Data Representation Standard", STD 67, RFC 4506, May 2006. 8.2. Informative References [AFS1] Howard, J., "An Overview of the Andrew File System"", Proc. 1988 USENIX Winter Tech. Conf. pp. 23-26, February 1988. [AFS2] Howard, J., Kazar, M., Menees, S., Nichols, D., Satyanarayanan, M., Sidebotham, R., and M. West, "Scale and Performance in a Distributed File System", ACM Trans. Comp. Sys. Vol. 6, No. 1, pp. 51-81, February 1988. [AFS3-RX] Zayas, E., "AFS-3 Programmer's Reference: Specification for the Rx Remote Procedure Call Facility", Transarc Corp. Tech. Rep. FS-00-D164, August 1991. [CMU-ITC-83-025] Morris, J., Van Houweling, D., and K. Slack, "The Information Technology Center", CMU ITC Tech. Rep. CMU- ITC-83-025, 1983. [CMU-ITC-84-020] West, M., "VICE File System Services", CMU ITC Tech. Rep. CMU-ITC-84-020, August 1984. [VICE1] Satyanarayanan, M., Howard, J., Nichols, D., Sidebotham, R., Spector, A., and M. West, "The ITC Distributed File System: Principles and Design", Proc. 10th ACM Symp. Operating Sys. Princ. Vol. 19, No. 5, December 1985. [dce_rpc] The Open Group, "CAE Specification, DCE 1.1: Remote Procedure Call", CAE C706, August 1997. Appendix A. Base Type Definitions typedef afs_int8 int; typedef afs_uint8 unsigned int; typedef afs_int16 int; typedef afs_uint16 unsigned int; typedef afs_int32 int; typedef afs_uint32 unsigned int; typedef afs_int64 hyper; typedef afs_uint64 unsigned hyper; Keiser Expires December 4, 2011 [Page 9] Internet-Draft AFS-3 XDR Primitive Types June 2011 Author's Address Thomas Keiser Sine Nomine Associates 43596 Blacksmith Square Ashburn, VA 20147 USA Phone: +1 703 723 6673 Email: tkeiser@sinenomine.net Keiser Expires December 4, 2011 [Page 10]