IETF                                                           T. Keiser
Internet-Draft                                               Sine Nomine
Intended status: BCP                                       March 7, 2011
Expires: September 8, 2011


        AFS-3 Extensible XDR Discriminated Union Primitive Type
                     draft-keiser-afs3-xdr-union-00

Abstract

   AFS-3 relies upon XDR to carry Rx RPC call payloads.  XDR
   discriminated unions are ill-suited to cases where the protocol needs
   to evolve without inventing new RPCs, i.e., unknown discriminant
   values cause the entire XDR payload to fail the decoding step.  While
   this can be circumvented through the use of opaque payloads (and
   recursive XDR invocations), such solutions are inelegant and
   difficult to implement.  This memo defines a new XDR primitive type,
   "afs-union", which is derived from the XDR discriminated union
   primitive type, but with two key variations: 1) each leg contains a
   length field, and 2) no default leg is supported.

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 September 8, 2011.

Copyright Notice

   Copyright (c) 2011 IETF Trust and the persons identified as the



Keiser                  Expires September 8, 2011               [Page 1]


Internet-Draft         AFS-3 Extensible XDR Union             March 2011


   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.  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 . . . . . . . . . . . . . . . . . . . . . . . . . . 3
   3.  AFS-3 Discriminated Union . . . . . . . . . . . . . . . . . . . 4
     3.1.  AFS-3 Union Type  . . . . . . . . . . . . . . . . . . . . . 4
     3.2.  RPC-L Changes . . . . . . . . . . . . . . . . . . . . . . . 5
     3.3.  Encoding  . . . . . . . . . . . . . . . . . . . . . . . . . 6
     3.4.  Decoding  . . . . . . . . . . . . . . . . . . . . . . . . . 6
   4.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . 7
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 7
   6.  AFS Assign Numbers Registrar Considerations . . . . . . . . . . 7
   7.  Security Considerations . . . . . . . . . . . . . . . . . . . . 7
   8.  References  . . . . . . . . . . . . . . . . . . . . . . . . . . 7
     8.1.  Normative References  . . . . . . . . . . . . . . . . . . . 7
     8.2.  Informative References  . . . . . . . . . . . . . . . . . . 7
   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . . . 8




















Keiser                  Expires September 8, 2011               [Page 2]


Internet-Draft         AFS-3 Extensible XDR Union             March 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.  XDR provides a discriminated union
   type.  However, the semantics of the discriminated union base type do
   not lend themselves to evolution of the discriminator namespace:
   introduction of new discriminators--when there is no default leg--
   cause the remainder of the XDR octet stream to be un-parseable (due
   to the lack of a length field in the encoding) by older peers.  This
   memo introduces a new XDR base type that is identical to the XDR
   discriminated union, except that: 1) each leg contains a length
   field, and 2) the default leg is disallowed.

1.1.  Abbreviations

   AFS    -  Historically, AFS stood for the Andrew File System; AFS no
           longer stands for anything

   RPC    -  Remote Procedure Call

   Rx     -  AFS-3 Remote Procedure Call Mechanism

   XDR    -  eXternal Data Representation


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




Keiser                  Expires September 8, 2011               [Page 3]


Internet-Draft         AFS-3 Extensible XDR Union             March 2011


3.  AFS-3 Discriminated Union

   The AFS-3 discriminated union will contain a length field in every
   leg so that decoding peers can always figure out the offset of the
   next object in the stream.  For small legs, this will result in
   significant encoding inefficiency, but it is necessary to permit the
   union to evolve over time (without peers failing to decode the entire
   XDR stream).

3.1.  AFS-3 Union Type

   The definition of the AFS-3 discriminated union is derived from the
   XDR union defined in section 4.15 of [RFC4506].  Unlike XDR
   discriminated unions, the types mapped to each arm of the union need
   not be defined a priori.  Instead, the length of the arm is always
   included in the wire encoding along with the discriminant value, thus
   permitting the decoder to continue decoding past an unknown
   discriminant in an XDR octet stream.  How undefined discriminator
   values are handled by the decoder is deliberately left unspecified by
   this document.  Each standards-track afs-union will have to define
   its own semantics for handling unknown discriminants.  AFS-3
   discriminated unions are defined in RPC-L as follows:

       afs-union switch (discriminant-definition) {
       case discriminant-value-A:
          arm-declaration-A;
       case discriminant-value-B:
          arm-declaration-B;
       ...
       } identifier;

                                 Figure 1

   Because the discriminant namespace of an AFS-3 union must be capable
   of evolving over time, it is not possible to support a default leg.

   The AFS-3 discriminated union is encoded on the wire as: a 4-octet
   discriminant, followed by a 4-octet arm length, and finally the
   variable-length implied arm.  The arm length field shall count the
   total octets present in the union encoding: 8 octets for the header,
   plus the total length of the implied arm.

                0   1   2   3
              +---+---+---+---+---+---+---+---+---+---+---+---+
              |  discriminant |   arm length  |  implied arm  |
              +---+---+---+---+---+---+---+---+---+---+---+---+
              |<---4 octets-->|<---4 octets-->|




Keiser                  Expires September 8, 2011               [Page 4]


Internet-Draft         AFS-3 Extensible XDR Union             March 2011


                                 Figure 2

3.2.  RPC-L Changes

   In order to implement the above, the XDR grammar, as specified in
   Section 6.3 of [RFC4506], will need to be modified in the following
   ways:

   o  "type-specifier" will require a new production rule mapping to
      "afs-union-type-spec", and

   o  an "afs-union-type-spec" production rule will need to be defined.

   The "type-specifier" grammar will now include a new production rule
   for "afs-union-type-spec":

       type-specifier:
            [ "unsigned" ] "int"
          | [ "unsigned" ] "hyper"
          | "float"
          | "double"
          | "quadruple"
          | "bool"
          | enum-type-spec
          | struct-type-spec
          | union-type-spec
          | identifier
          | afs-union-type-spec

                                 Figure 3

   The new "afs-union-type-spec" production rule, and the production
   rule for its nonterminal symbol dependency "afs-union-body", are
   defined as follows:

       afs-union-type-spec:
          "afs-union" afs-union-body

       afs-union-body:
          "switch" "(" declaration ")" "{"
             case-spec
             case-spec *
          "}"

                                 Figure 4






Keiser                  Expires September 8, 2011               [Page 5]


Internet-Draft         AFS-3 Extensible XDR Union             March 2011


3.3.  Encoding

   The encoding of an AFS-3 extensible union shall follow the same rules
   as an XDR discriminated union, except for the additional encoding
   step for the union length field.  The wire encoding SHALL consist of:

   1.  an XDR 32-bit unsigned integer (see Section 4.2 of [RFC4506])
       encoding the discriminator,

   2.  an XDR 32-bit unsigned integer encoding the union length (the
       value stored in this field MUST be computed using the formula
       discussed in Section 3.1), and

   3.  the XDR-encoded implied leg.

3.4.  Decoding

   It is RECOMMENDED that decoding of an AFS-3 extensible union proceed
   using the following algorithm:

   1.  XDR decode the 32-bit unsigned integer containing the tag

   2.  XDR decode the 32-bit unsigned integer containing the length

   3.  If this is a known tag:

       1.  Lookup the tag and compare the expected length with the
           previously-decoded length field.

       2.  If the expected and actual lengths match:

           1.  The implied leg's payload should be decoded according to
               the XDR specification.

       3.  If the expected and actual lengths do not match:

           1.  The union SHALL be marked as failed to decode.

   4.  However, if this is an unknown tag:

       1.  The union SHALL be marked as failed to decode.

   5.  XDR decoding continues at the current offset plus the length
       specified in the previously-decoded length field.







Keiser                  Expires September 8, 2011               [Page 6]


Internet-Draft         AFS-3 Extensible XDR Union             March 2011


4.  Acknowledgements

   The editor would like to thank Jeffrey Hutzelman for proposing
   standardization of a new XDR primitive type; and Andrew Deason, Simon
   Wilkinson, Derrick Brashear, and Matt Benjamin for helping to refine
   the design of this extensible union type.


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

   Users of this extensible type should understand that any Rx XDR
   payload is only as secure as the security class bound to the Rx
   connection in question.  This document merely standardizes a
   primitive type; it is up to the authors of standards defining new
   types--upon the "afs-union" primitive type--to ensure that the
   contents of their types are only marshalled over sufficiently-secure
   security classes.


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.

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



Keiser                  Expires September 8, 2011               [Page 7]


Internet-Draft         AFS-3 Extensible XDR Union             March 2011


              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.


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 September 8, 2011               [Page 8]