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

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

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;
          

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

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:

• "type-specifier" will require a new production rule mapping to "afs-union-type-spec", and
• 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
          

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 *
       "}"
          

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.

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

8.2. Informative References

Author's Address