N/A                                                            T. Keiser
Internet-Draft                                            A. Deason, Ed.
Intended status: Informational                               Sine Nomine
Expires: March 14, 2013                               September 10, 2012


              AFS-3 Rx RPC XDR Primitive Type Definitions
                draft-keiser-afs3-xdr-primitive-types-01

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.

AFS-3 Document State

   This document is in state "draft", as per the document state
   definitions set forth in [I-D.wilkinson-afs3-standardisation].

Status of this Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.  This document may not be modified,
   and derivative works of it may not be created, and it may not be
   published except as an Internet-Draft.

   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 March 14, 2013.

Copyright Notice




Keiser & Deason          Expires March 14, 2013                 [Page 1]


Internet-Draft          AFS-3 XDR Primitive Types         September 2012


   Copyright (c) 2012 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.


Table of Contents

   1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.1.  Purpose  . . . . . . . . . . . . . . . . . . . . . . . . .  3
     1.2.  Abbreviations  . . . . . . . . . . . . . . . . . . . . . .  3
   2.  Conventions  . . . . . . . . . . . . . . . . . . . . . . . . .  4
   3.  Primitive Integer Types  . . . . . . . . . . . . . . . . . . .  4
     3.1.  char . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
     3.2.  unsigned char  . . . . . . . . . . . . . . . . . . . . . .  5
     3.3.  short  . . . . . . . . . . . . . . . . . . . . . . . . . .  5
     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 . . . . . . . . . . . . . . . . . . . . . . . . . .  9
     8.1.  Normative References . . . . . . . . . . . . . . . . . . .  9
     8.2.  Informative References . . . . . . . . . . . . . . . . . .  9
   Appendix A.  Base Type Definitions . . . . . . . . . . . . . . . . 10
   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10

















Keiser & Deason          Expires March 14, 2013                 [Page 2]


Internet-Draft          AFS-3 XDR Primitive Types         September 2012


1.  Introduction

   AFS-3 [CMU-ITC-88-062] [CMU-ITC-87-068] is a distributed file system
   that has its origins in the VICE project [CMU-ITC-84-020]
   [CMU-ITC-85-039] 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.

1.1.  Purpose

   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, the AFS-3
   RPC-L grammar references 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.2.  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

   RPC-L    -  Rx RPC Interface Definition Language (fork of ONC RPC
             [RFC5531] .x file format)






Keiser & Deason          Expires March 14, 2013                 [Page 3]


Internet-Draft          AFS-3 XDR Primitive Types         September 2012


   Rx       -  The Remote Procedure Call mechanism utilized by AFS-3
             [AFS3-RX]

   UUID     -  Universally Unique IDentifier

   XDR      -  eXternal Data Representation [RFC4506]


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.







Keiser & Deason          Expires March 14, 2013                 [Page 4]


Internet-Draft          AFS-3 XDR Primitive Types         September 2012


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.

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:

       /*
        * Copyright 2000, International Business Machines Corporation
        * and others.  All Rights Reserved.
        *
        * This software has been released under the terms of the IBM
        * Public License.  For details, see the LICENSE file in the
        * top-level source directory or online at
        * http://www.openafs.org/dl/license10.html
        */

     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];
     };



Keiser & Deason          Expires March 14, 2013                 [Page 5]


Internet-Draft          AFS-3 XDR Primitive Types         September 2012


     typedef struct afsUUID afsUUID;


   An afsUUID type is XDR encoded on the wire as follows:

     (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




Keiser & Deason          Expires March 14, 2013                 [Page 6]


Internet-Draft          AFS-3 XDR Primitive Types         September 2012


   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

   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.





Keiser & Deason          Expires March 14, 2013                 [Page 7]


Internet-Draft          AFS-3 XDR Primitive Types         September 2012


   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
        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



Keiser & Deason          Expires March 14, 2013                 [Page 8]


Internet-Draft          AFS-3 XDR Primitive Types         September 2012


8.1.  Normative References

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, March 1997.

   [RFC4506]  Eisler, M., "XDR: External Data Representation Standard",
              STD 67, RFC 4506, May 2006.

8.2.  Informative References

   [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.

   [CMU-ITC-85-039]
              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.

   [CMU-ITC-87-068]
              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.

   [CMU-ITC-88-062]
              Howard, J., "An Overview of the Andrew File System"",
              Proc. 1988 USENIX Winter Tech. Conf. pp. 23-26,
              February 1988.

   [DCE-RPC]  The Open Group, "CAE Specification, DCE 1.1: Remote
              Procedure Call", CAE C706, August 1997.

   [I-D.wilkinson-afs3-standardisation]
              Wilkinson, S., "Options for AFS Standardisation",
              draft-wilkinson-afs3-standardisation-00 (work in
              progress), June 2010.




Keiser & Deason          Expires March 14, 2013                 [Page 9]


Internet-Draft          AFS-3 XDR Primitive Types         September 2012


   [RFC5531]  Thurlow, R., "RPC: Remote Procedure Call Protocol
              Specification Version 2", RFC 5531, May 2009.


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;


Authors' Addresses

   Thomas Keiser
   Sine Nomine Associates
   43596 Blacksmith Square
   Ashburn, VA  20147
   USA

   Email: tkeiser@gmail.com


   Andrew Deason (editor)
   Sine Nomine Associates
   43596 Blacksmith Square
   Ashburn, Virginia  20147-4606
   USA

   Phone: +1 703 723 6673
   Email: adeason@sinenomine.net
















Keiser & Deason          Expires March 14, 2013                [Page 10]