AFS-3 Rx RPC XDR Primitive Type Definitions

AFS-3 is a distributed file system that has its origins in the VICE project at the Carnegie Mellon University Information Technology Center , 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 . 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 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.

Historically, AFS stood for the Andrew File System; AFS no longer stands for anything The Distributed Computing Environment Least-Significant Bit Most-Significant Bit Remote Procedure Call Rx RPC Interface Definition Language (fork of ONC RPC .x file format) The Remote Procedure Call mechanism utilized by AFS-3 Universally Unique IDentifier eXternal Data Representation

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.

AFS-3 defines a number of special types which are direct mappings onto existing XDR types. Thus, these types are essentially XDR typedefs:

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

This type is considered deprecated; future protocol specifications should reference the "afs_int8" type instead.

This type is considered deprecated; future protocol specifications should reference the "afs_uint8" type instead.

This type is considered deprecated; future protocol specifications should reference the "afs_int16" type instead.

This type is considered deprecated; future protocol specifications should reference the "afs_uint16" type instead.

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.

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 ). The C data structure definition for such a UUID is as follows:

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

afsUUID XDR encoding

XDR encoding an "afsUUID" type SHALL involve the following sequence of operations: Encode "time_low" field as an XDR unsigned integer (afs_uint32) Encode "time_mid" field as an XDR unsigned integer Encode "time_hi_and_version" field as an XDR unsigned integer Encode "clock_seq_hi_and_reserved" field as an XDR signed integer Encode "clock_seq_low" field as an XDR signed integer Encode "node[0]" field as an XDR signed integer Encode "node[1]" field as an XDR signed integer Encode "node[2]" field as an XDR signed integer Encode "node[3]" field as an XDR signed integer Encode "node[4]" field as an XDR signed integer 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.

XDR decoding an "afsUUID" type SHALL involve the following sequence of operations: Decode an XDR unsigned integer into the "time_low" field 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. 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. 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. 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. 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. 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. 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. 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. 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. 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.

This memo includes no request to IANA.

This memo includes no request to the AFS Assigned Numbers Registrar.

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.