doc: Add RFC documents

1 files changed, 1011 insertions, 0 deletions

diff --git a/doc/rfc/rfc1831.txt b/doc/rfc/rfc1831.txt
new file mode 100644
index 0000000..0556c9e
--- /dev/null
+++ b/doc/rfc/rfc1831.txt
@@ -0,0 +1,1011 @@
+
+
+
+
+
+
+Network Working Group                                      R. Srinivasan
+Request for Comments: 1831                              Sun Microsystems
+Category: Standards Track                                    August 1995
+
+
+      RPC: Remote Procedure Call Protocol Specification Version 2
+
+Status of this Memo
+
+   This document specifies an Internet standards track protocol for the
+   Internet community, and requests discussion and suggestions for
+   improvements.  Please refer to the current edition of the "Internet
+   Official Protocol Standards" (STD 1) for the standardization state
+   and status of this protocol.  Distribution of this memo is unlimited.
+
+ABSTRACT
+
+   This document describes the ONC Remote Procedure Call (ONC RPC
+   Version 2) protocol as it is currently deployed and accepted.  "ONC"
+   stands for "Open Network Computing".
+
+TABLE OF CONTENTS
+
+      1. INTRODUCTION                                              2
+      2. TERMINOLOGY                                               2
+      3. THE RPC MODEL                                             2
+      4. TRANSPORTS AND SEMANTICS                                  4
+      5. BINDING AND RENDEZVOUS INDEPENDENCE                       5
+      6. AUTHENTICATION                                            5
+      7. RPC PROTOCOL REQUIREMENTS                                 5
+      7.1 RPC Programs and Procedures                              6
+      7.2 Authentication                                           7
+      7.3 Program Number Assignment                                8
+      7.4 Other Uses of the RPC Protocol                           8
+      7.4.1 Batching                                               8
+      7.4.2 Broadcast Remote Procedure Calls                       8
+      8. THE RPC MESSAGE PROTOCOL                                  9
+      9. AUTHENTICATION PROTOCOLS                                 12
+      9.1 Null Authentication                                     13
+      10. RECORD MARKING STANDARD                                 13
+      11. THE RPC LANGUAGE                                        13
+      11.1 An Example Service Described in the RPC Language       13
+      11.2 The RPC Language Specification                         14
+      11.3 Syntax Notes                                           15
+      APPENDIX A: SYSTEM AUTHENTICATION                           16
+      REFERENCES                                                  17
+      Security Considerations                                     18
+      Author's Address                                            18
+
+
+
+Srinivasan                  Standards Track                     [Page 1]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+1. INTRODUCTION
+
+   This document specifies version two of the message protocol used in
+   ONC Remote Procedure Call (RPC).  The message protocol is specified
+   with the eXternal Data Representation (XDR) language [9].  This
+   document assumes that the reader is familiar with XDR.  It does not
+   attempt to justify remote procedure calls systems or describe their
+   use.  The paper by Birrell and Nelson [1] is recommended as an
+   excellent background for the remote procedure call concept.
+
+2. TERMINOLOGY
+
+   This document discusses clients, calls, servers, replies, services,
+   programs, procedures, and versions.  Each remote procedure call has
+   two sides: an active client side that makes the call to a server,
+   which sends back a reply.  A network service is a collection of one
+   or more remote programs.  A remote program implements one or more
+   remote procedures; the procedures, their parameters, and results are
+   documented in the specific program's protocol specification.  A
+   server may support more than one version of a remote program in order
+   to be compatible with changing protocols.
+
+   For example, a network file service may be composed of two programs.
+   One program may deal with high-level applications such as file system
+   access control and locking.  The other may deal with low-level file
+   input and output and have procedures like "read" and "write".  A
+   client of the network file service would call the procedures
+   associated with the two programs of the service on behalf of the
+   client.
+
+   The terms client and server only apply to a particular transaction; a
+   particular hardware entity (host) or software entity (process or
+   program) could operate in both roles at different times.  For
+   example, a program that supplies remote execution service could also
+   be a client of a network file service.
+
+3. THE RPC MODEL
+
+   The ONC RPC protocol is based on the remote procedure call model,
+   which is similar to the local procedure call model.  In the local
+   case, the caller places arguments to a procedure in some well-
+   specified location (such as a register window).  It then transfers
+   control to the procedure, and eventually regains control.  At that
+   point, the results of the procedure are extracted from the well-
+   specified location, and the caller continues execution.
+
+
+
+
+
+
+Srinivasan                  Standards Track                     [Page 2]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+   The remote procedure call model is similar.  One thread of control
+   logically winds through two processes: the caller's process, and a
+   server's process.  The caller process first sends a call message to
+   the server process and waits (blocks) for a reply message.  The call
+   message includes the procedure's parameters, and the reply message
+   includes the procedure's results.  Once the reply message is
+   received, the results of the procedure are extracted, and caller's
+   execution is resumed.
+
+   On the server side, a process is dormant awaiting the arrival of a
+   call message.  When one arrives, the server process extracts the
+   procedure's parameters, computes the results, sends a reply message,
+   and then awaits the next call message.
+
+   In this model, only one of the two processes is active at any given
+   time.  However, this model is only given as an example.  The ONC RPC
+   protocol makes no restrictions on the concurrency model implemented,
+   and others are possible.  For example, an implementation may choose
+   to have RPC calls be asynchronous, so that the client may do useful
+   work while waiting for the reply from the server.  Another
+   possibility is to have the server create a separate task to process
+   an incoming call, so that the original server can be free to receive
+   other requests.
+
+   There are a few important ways in which remote procedure calls differ
+   from local procedure calls:
+
+      1. Error handling: failures of the remote server or network must
+      be handled when using remote procedure calls.
+
+      2. Global variables and side-effects: since the server does not
+      have access to the client's address space, hidden arguments cannot
+      be passed as global variables or returned as side effects.
+
+      3. Performance:  remote procedures usually operate one or more
+      orders of magnitude slower than local procedure calls.
+
+      4. Authentication: since remote procedure calls can be transported
+      over unsecured networks, authentication may be necessary.
+      Authentication prevents one entity from masquerading as some other
+      entity.
+
+   The conclusion is that even though there are tools to automatically
+   generate client and server libraries for a given service, protocols
+   must still be designed carefully.
+
+
+
+
+
+
+Srinivasan                  Standards Track                     [Page 3]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+4. TRANSPORTS AND SEMANTICS
+
+   The RPC protocol can be implemented on several different transport
+   protocols.  The RPC protocol does not care how a message is passed
+   from one process to another, but only with specification and
+   interpretation of messages.  However, the application may wish to
+   obtain information about (and perhaps control over) the transport
+   layer through an interface not specified in this document.  For
+   example, the transport protocol may impose a restriction on the
+   maximum size of RPC messages, or it may be stream-oriented like TCP
+   with no size limit.  The client and server must agree on their
+   transport protocol choices.
+
+   It is important to point out that RPC does not try to implement any
+   kind of reliability and that the application may need to be aware of
+   the type of transport protocol underneath RPC.  If it knows it is
+   running on top of a reliable transport such as TCP [6], then most of
+   the work is already done for it.  On the other hand, if it is running
+   on top of an unreliable transport such as UDP [7], it must implement
+   its own time-out, retransmission, and duplicate detection policies as
+   the RPC protocol does not provide these services.
+
+   Because of transport independence, the RPC protocol does not attach
+   specific semantics to the remote procedures or their execution
+   requirements.  Semantics can be inferred from (but should be
+   explicitly specified by) the underlying transport protocol.  For
+   example, consider RPC running on top of an unreliable transport such
+   as UDP.  If an application retransmits RPC call messages after time-
+   outs, and does not receive a reply, it cannot infer anything about
+   the number of times the procedure was executed.  If it does receive a
+   reply, then it can infer that the procedure was executed at least
+   once.
+
+   A server may wish to remember previously granted requests from a
+   client and not regrant them in order to insure some degree of
+   execute-at-most-once semantics.  A server can do this by taking
+   advantage of the transaction ID that is packaged with every RPC
+   message.  The main use of this transaction ID is by the client RPC
+   entity in matching replies to calls.  However, a client application
+   may choose to reuse its previous transaction ID when retransmitting a
+   call.  The server may choose to remember this ID after executing a
+   call and not execute calls with the same ID in order to achieve some
+   degree of execute-at-most-once semantics.  The server is not allowed
+   to examine this ID in any other way except as a test for equality.
+
+   On the other hand, if using a "reliable" transport such as TCP, the
+   application can infer from a reply message that the procedure was
+   executed exactly once, but if it receives no reply message, it cannot
+
+
+
+Srinivasan                  Standards Track                     [Page 4]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+   assume that the remote procedure was not executed.  Note that even if
+   a connection-oriented protocol like TCP is used, an application still
+   needs time-outs and reconnection to handle server crashes.
+
+   There are other possibilities for transports besides datagram- or
+   connection-oriented protocols.  For example, a request-reply protocol
+   such as VMTP [2] is perhaps a natural transport for RPC.  ONC RPC
+   uses both TCP and UDP transport protocols.  Section 10 (RECORD
+   MARKING STANDARD) describes the mechanism employed by ONC RPC to
+   utilize a connection-oriented, stream-oriented transport such as TCP.
+
+5. BINDING AND RENDEZVOUS INDEPENDENCE
+
+   The act of binding a particular client to a particular service and
+   transport parameters is NOT part of this RPC protocol specification.
+   This important and necessary function is left up to some higher-level
+   software.
+
+   Implementors could think of the RPC protocol as the jump-subroutine
+   instruction ("JSR") of a network; the loader (binder) makes JSR
+   useful, and the loader itself uses JSR to accomplish its task.
+   Likewise, the binding software makes RPC useful, possibly using RPC
+   to accomplish this task.
+
+6. AUTHENTICATION
+
+   The RPC protocol provides the fields necessary for a client to
+   identify itself to a service, and vice-versa, in each call and reply
+   message.  Security and access control mechanisms can be built on top
+   of this message authentication.  Several different authentication
+   protocols can be supported.  A field in the RPC header indicates
+   which protocol is being used. More information on specific
+   authentication protocols is in section 9: "Authentication Protocols".
+
+7. RPC PROTOCOL REQUIREMENTS
+
+   The RPC protocol must provide for the following:
+
+      (1) Unique specification of a procedure to be called.
+      (2) Provisions for matching response messages to request messages.
+      (3) Provisions for authenticating the caller to service and
+          vice-versa.
+
+
+
+
+
+
+
+
+
+Srinivasan                  Standards Track                     [Page 5]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+   Besides these requirements, features that detect the following are
+   worth supporting because of protocol roll-over errors, implementation
+   bugs, user error, and network administration:
+
+      (1) RPC protocol mismatches.
+      (2) Remote program protocol version mismatches.
+      (3) Protocol errors (such as misspecification of a procedure's
+          parameters).
+      (4) Reasons why remote authentication failed.
+      (5) Any other reasons why the desired procedure was not called.
+
+7.1 RPC Programs and Procedures
+
+   The RPC call message has three unsigned integer fields -- remote
+   program number, remote program version number, and remote procedure
+   number -- which uniquely identify the procedure to be called.
+   Program numbers are administered by a central authority
+   (rpc@sun.com).  Once implementors have a program number, they can
+   implement their remote program; the first implementation would most
+   likely have the version number 1.  Because most new protocols evolve,
+   a version field of the call message identifies which version of the
+   protocol the caller is using.  Version numbers enable support of both
+   old and new protocols through the same server process.
+
+   The procedure number identifies the procedure to be called.  These
+   numbers are documented in the specific program's protocol
+   specification.  For example, a file service's protocol specification
+   may state that its procedure number 5 is "read" and procedure number
+   12 is "write".
+
+   Just as remote program protocols may change over several versions,
+   the actual RPC message protocol could also change.  Therefore, the
+   call message also has in it the RPC version number, which is always
+   equal to two for the version of RPC described here.
+
+   The reply message to a request message has enough information to
+   distinguish the following error conditions:
+
+      (1) The remote implementation of RPC does not support protocol
+      version 2.  The lowest and highest supported RPC version numbers
+      are returned.
+
+      (2) The remote program is not available on the remote system.
+
+      (3) The remote program does not support the requested version
+      number.  The lowest and highest supported remote program version
+      numbers are returned.
+
+
+
+
+Srinivasan                  Standards Track                     [Page 6]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+      (4) The requested procedure number does not exist.  (This is
+      usually a client side protocol or programming error.)
+
+      (5) The parameters to the remote procedure appear to be garbage
+      from the server's point of view.  (Again, this is usually caused
+      by a disagreement about the protocol between client and service.)
+
+7.2 Authentication
+
+   Provisions for authentication of caller to service and vice-versa are
+   provided as a part of the RPC protocol.  The call message has two
+   authentication fields, the credential and verifier.  The reply
+   message has one authentication field, the response verifier.  The RPC
+   protocol specification defines all three fields to be the following
+   opaque type (in the eXternal Data Representation (XDR) language [9]):
+
+      enum auth_flavor {
+         AUTH_NONE       = 0,
+         AUTH_SYS        = 1,
+         AUTH_SHORT      = 2
+         /* and more to be defined */
+      };
+
+      struct opaque_auth {
+         auth_flavor flavor;
+         opaque body<400>;
+      };
+
+   In other words, any "opaque_auth" structure is an "auth_flavor"
+   enumeration followed by up to 400 bytes which are opaque to
+   (uninterpreted by) the RPC protocol implementation.
+
+   The interpretation and semantics of the data contained within the
+   authentication fields is specified by individual, independent
+   authentication protocol specifications.  (Section 9 defines the
+   various authentication protocols.)
+
+   If authentication parameters were rejected, the reply message
+   contains information stating why they were rejected.
+
+
+
+
+
+
+
+
+
+
+
+
+Srinivasan                  Standards Track                     [Page 7]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+7.3 Program Number Assignment
+
+   Program numbers are given out in groups of hexadecimal 20000000
+   (decimal 536870912) according to the following chart:
+
+              0 - 1fffffff   defined by rpc@sun.com
+       20000000 - 3fffffff   defined by user
+       40000000 - 5fffffff   transient
+       60000000 - 7fffffff   reserved
+       80000000 - 9fffffff   reserved
+       a0000000 - bfffffff   reserved
+       c0000000 - dfffffff   reserved
+       e0000000 - ffffffff   reserved
+
+   The first group is a range of numbers administered by rpc@sun.com and
+   should be identical for all sites.  The second range is for
+   applications peculiar to a particular site.  This range is intended
+   primarily for debugging new programs.  When a site develops an
+   application that might be of general interest, that application
+   should be given an assigned number in the first range.  Application
+   developers may apply for blocks of RPC program numbers in the first
+   range by sending electronic mail to "rpc@sun.com".  The third group
+   is for applications that generate program numbers dynamically.  The
+   final groups are reserved for future use, and should not be used.
+
+7.4 Other Uses of the RPC Protocol
+
+   The intended use of this protocol is for calling remote procedures.
+   Normally, each call message is matched with a reply message.
+   However, the protocol itself is a message-passing protocol with which
+   other (non-procedure call) protocols can be implemented.
+
+7.4.1 Batching
+
+   Batching is useful when a client wishes to send an arbitrarily large
+   sequence of call messages to a server.  Batching typically uses
+   reliable byte stream protocols (like TCP) for its transport.  In the
+   case of batching, the client never waits for a reply from the server,
+   and the server does not send replies to batch calls.  A sequence of
+   batch calls is usually terminated by a legitimate remote procedure
+   call operation in order to flush the pipeline and get positive
+   acknowledgement.
+
+7.4.2 Broadcast Remote Procedure Calls
+
+   In broadcast protocols, the client sends a broadcast call to the
+   network and waits for numerous replies.  This requires the use of
+   packet-based protocols (like UDP) as its transport protocol.  Servers
+
+
+
+Srinivasan                  Standards Track                     [Page 8]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+   that support broadcast protocols usually respond only when the call
+   is successfully processed and are silent in the face of errors, but
+   this varies with the application.
+
+   The principles of broadcast RPC also apply to multicasting - an RPC
+   request can be sent to a multicast address.
+
+8. THE RPC MESSAGE PROTOCOL
+
+   This section defines the RPC message protocol in the XDR data
+   description language [9].
+
+      enum msg_type {
+         CALL  = 0,
+         REPLY = 1
+      };
+
+   A reply to a call message can take on two forms: The message was
+   either accepted or rejected.
+
+      enum reply_stat {
+         MSG_ACCEPTED = 0,
+         MSG_DENIED   = 1
+      };
+
+   Given that a call message was accepted, the following is the status
+   of an attempt to call a remote procedure.
+
+      enum accept_stat {
+         SUCCESS       = 0, /* RPC executed successfully             */
+         PROG_UNAVAIL  = 1, /* remote hasn't exported program        */
+         PROG_MISMATCH = 2, /* remote can't support version #        */
+         PROC_UNAVAIL  = 3, /* program can't support procedure       */
+         GARBAGE_ARGS  = 4, /* procedure can't decode params         */
+         SYSTEM_ERR    = 5  /* errors like memory allocation failure */
+      };
+
+   Reasons why a call message was rejected:
+
+      enum reject_stat {
+         RPC_MISMATCH = 0, /* RPC version number != 2          */
+         AUTH_ERROR = 1    /* remote can't authenticate caller */
+      };
+
+   Why authentication failed:
+
+      enum auth_stat {
+         AUTH_OK           = 0,  /* success                          */
+
+
+
+Srinivasan                  Standards Track                     [Page 9]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+         /*
+          * failed at remote end
+          */
+         AUTH_BADCRED      = 1,  /* bad credential (seal broken)     */
+         AUTH_REJECTEDCRED = 2,  /* client must begin new session    */
+         AUTH_BADVERF      = 3,  /* bad verifier (seal broken)       */
+         AUTH_REJECTEDVERF = 4,  /* verifier expired or replayed     */
+         AUTH_TOOWEAK      = 5,  /* rejected for security reasons    */
+         /*
+          * failed locally
+          */
+         AUTH_INVALIDRESP  = 6,  /* bogus response verifier          */
+         AUTH_FAILED       = 7   /* reason unknown                   */
+      };
+
+   The RPC message:
+
+   All messages start with a transaction identifier, xid, followed by a
+   two-armed discriminated union.  The union's discriminant is a
+   msg_type which switches to one of the two types of the message.  The
+   xid of a REPLY message always matches that of the initiating CALL
+   message.  NB: The xid field is only used for clients matching reply
+   messages with call messages or for servers detecting retransmissions;
+   the service side cannot treat this id as any type of sequence number.
+
+      struct rpc_msg {
+         unsigned int xid;
+         union switch (msg_type mtype) {
+         case CALL:
+            call_body cbody;
+         case REPLY:
+            reply_body rbody;
+         } body;
+      };
+
+   Body of an RPC call:
+
+   In version 2 of the RPC protocol specification, rpcvers must be equal
+   to 2.  The fields prog, vers, and proc specify the remote program,
+   its version number, and the procedure within the remote program to be
+   called.  After these fields are two authentication parameters:  cred
+   (authentication credential) and verf (authentication verifier).  The
+   two authentication parameters are followed by the parameters to the
+   remote procedure, which are specified by the specific program
+   protocol.
+
+   The purpose of the authentication verifier is to validate the
+   authentication credential.  Note that these two items are
+
+
+
+Srinivasan                  Standards Track                    [Page 10]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+   historically separate, but are always used together as one logical
+   entity.
+
+      struct call_body {
+         unsigned int rpcvers;       /* must be equal to two (2) */
+         unsigned int prog;
+         unsigned int vers;
+         unsigned int proc;
+         opaque_auth  cred;
+         opaque_auth  verf;
+         /* procedure specific parameters start here */
+      };
+
+   Body of a reply to an RPC call:
+
+      union reply_body switch (reply_stat stat) {
+      case MSG_ACCEPTED:
+         accepted_reply areply;
+      case MSG_DENIED:
+         rejected_reply rreply;
+      } reply;
+
+   Reply to an RPC call that was accepted by the server:
+
+   There could be an error even though the call was accepted.  The first
+   field is an authentication verifier that the server generates in
+   order to validate itself to the client.  It is followed by a union
+   whose discriminant is an enum accept_stat.  The SUCCESS arm of the
+   union is protocol specific.  The PROG_UNAVAIL, PROC_UNAVAIL,
+   GARBAGE_ARGS, and SYSTEM_ERR arms of the union are void.  The
+   PROG_MISMATCH arm specifies the lowest and highest version numbers of
+   the remote program supported by the server.
+
+      struct accepted_reply {
+         opaque_auth verf;
+         union switch (accept_stat stat) {
+         case SUCCESS:
+            opaque results[0];
+            /*
+             * procedure-specific results start here
+             */
+          case PROG_MISMATCH:
+             struct {
+                unsigned int low;
+                unsigned int high;
+             } mismatch_info;
+          default:
+             /*
+
+
+
+Srinivasan                  Standards Track                    [Page 11]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+              * Void.  Cases include PROG_UNAVAIL, PROC_UNAVAIL,
+              * GARBAGE_ARGS, and SYSTEM_ERR.
+              */
+             void;
+          } reply_data;
+      };
+
+   Reply to an RPC call that was rejected by the server:
+
+   The call can be rejected for two reasons: either the server is not
+   running a compatible version of the RPC protocol (RPC_MISMATCH), or
+   the server rejects the identity of the caller (AUTH_ERROR). In case
+   of an RPC version mismatch, the server returns the lowest and highest
+   supported RPC version numbers.  In case of invalid authentication,
+   failure status is returned.
+
+      union rejected_reply switch (reject_stat stat) {
+      case RPC_MISMATCH:
+         struct {
+            unsigned int low;
+            unsigned int high;
+         } mismatch_info;
+      case AUTH_ERROR:
+         auth_stat stat;
+      };
+
+9. AUTHENTICATION PROTOCOLS
+
+   As previously stated, authentication parameters are opaque, but
+   open-ended to the rest of the RPC protocol.  This section defines two
+   standard "flavors" of authentication.  Implementors are free to
+   invent new authentication types, with the same rules of flavor number
+   assignment as there is for program number assignment.  The "flavor"
+   of a credential or verifier refers to the value of the "flavor" field
+   in the opaque_auth structure. Flavor numbers, like RPC program
+   numbers, are also administered centrally, and developers may assign
+   new flavor numbers by applying through electronic mail to
+   "rpc@sun.com".  Credentials and verifiers are represented as variable
+   length opaque data (the "body" field in the opaque_auth structure).
+
+   In this document, two flavors of authentication are described.  Of
+   these, Null authentication (described in the next subsection) is
+   mandatory - it must be available in all implementations.  System
+   authentication is described in Appendix A.  It is strongly
+   recommended that implementors include System authentication in their
+   implementations.  Many applications use this style of authentication,
+   and availability of this flavor in an implementation will enhance
+   interoperability.
+
+
+
+Srinivasan                  Standards Track                    [Page 12]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+9.1 Null Authentication
+
+   Often calls must be made where the client does not care about its
+   identity or the server does not care who the client is.  In this
+   case, the flavor of the RPC message's credential, verifier, and reply
+   verifier is "AUTH_NONE".  Opaque data associated with "AUTH_NONE" is
+   undefined.  It is recommended that the length of the opaque data be
+   zero.
+
+10. RECORD MARKING STANDARD
+
+   When RPC messages are passed on top of a byte stream transport
+   protocol (like TCP), it is necessary to delimit one message from
+   another in order to detect and possibly recover from protocol errors.
+   This is called record marking (RM).  One RPC message fits into one RM
+   record.
+
+   A record is composed of one or more record fragments.  A record
+   fragment is a four-byte header followed by 0 to (2**31) - 1 bytes of
+   fragment data.  The bytes encode an unsigned binary number; as with
+   XDR integers, the byte order is from highest to lowest.  The number
+   encodes two values -- a boolean which indicates whether the fragment
+   is the last fragment of the record (bit value 1 implies the fragment
+   is the last fragment) and a 31-bit unsigned binary value which is the
+   length in bytes of the fragment's data.  The boolean value is the
+   highest-order bit of the header; the length is the 31 low-order bits.
+   (Note that this record specification is NOT in XDR standard form!)
+
+11. THE RPC LANGUAGE
+
+   Just as there was a need to describe the XDR data-types in a formal
+   language, there is also need to describe the procedures that operate
+   on these XDR data-types in a formal language as well.  The RPC
+   Language is an extension to the XDR language, with the addition of
+   "program", "procedure", and "version" declarations.  The following
+   example is used to describe the essence of the language.
+
+11.1 An Example Service Described in the RPC Language
+
+   Here is an example of the specification of a simple ping program.
+
+   program PING_PROG {
+         /*
+          * Latest and greatest version
+          */
+         version PING_VERS_PINGBACK {
+            void
+            PINGPROC_NULL(void) = 0;
+
+
+
+Srinivasan                  Standards Track                    [Page 13]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+            /*
+             * Ping the client, return the round-trip time
+             * (in microseconds). Returns -1 if the operation
+             * timed out.
+             */
+            int
+            PINGPROC_PINGBACK(void) = 1;
+         } = 2;
+
+         /*
+          * Original version
+          */
+         version PING_VERS_ORIG {
+            void
+            PINGPROC_NULL(void) = 0;
+         } = 1;
+      } = 1;
+
+      const PING_VERS = 2;      /* latest version */
+
+   The first version described is PING_VERS_PINGBACK with two
+   procedures, PINGPROC_NULL and PINGPROC_PINGBACK.  PINGPROC_NULL takes
+   no arguments and returns no results, but it is useful for computing
+   round-trip times from the client to the server and back again.  By
+   convention, procedure 0 of any RPC protocol should have the same
+   semantics, and never require any kind of authentication.  The second
+   procedure is used for the client to have the server do a reverse ping
+   operation back to the client, and it returns the amount of time (in
+   microseconds) that the operation used.  The next version,
+   PING_VERS_ORIG, is the original version of the protocol and it does
+   not contain PINGPROC_PINGBACK procedure. It is useful for
+   compatibility with old client programs, and as this program matures
+   it may be dropped from the protocol entirely.
+
+11.2 The RPC Language Specification
+
+   The RPC language is identical to the XDR language defined in RFC
+   1014, except for the added definition of a "program-def" described
+   below.
+
+   program-def:
+      "program" identifier "{"
+         version-def
+         version-def *
+      "}" "=" constant ";"
+
+   version-def:
+      "version" identifier "{"
+
+
+
+Srinivasan                  Standards Track                    [Page 14]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+          procedure-def
+          procedure-def *
+      "}" "=" constant ";"
+
+   procedure-def:
+      type-specifier identifier "(" type-specifier
+        ("," type-specifier )* ")" "=" constant ";"
+
+11.3 Syntax Notes
+
+   (1) The following keywords are added and cannot be used as
+   identifiers: "program" and "version";
+
+   (2) A version name cannot occur more than once within the scope of a
+   program definition. Nor can a version number occur more than once
+   within the scope of a program definition.
+
+   (3) A procedure name cannot occur more than once within the scope of
+   a version definition. Nor can a procedure number occur more than once
+   within the scope of version definition.
+
+   (4) Program identifiers are in the same name space as constant and
+   type identifiers.
+
+   (5) Only unsigned constants can be assigned to programs, versions and
+   procedures.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Srinivasan                  Standards Track                    [Page 15]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+APPENDIX A: SYSTEM AUTHENTICATION
+
+   The client may wish to identify itself, for example, as it is
+   identified on a UNIX(tm) system.  The flavor of the client credential
+   is "AUTH_SYS".  The opaque data constituting the credential encodes
+   the following structure:
+
+      struct authsys_parms {
+         unsigned int stamp;
+         string machinename<255>;
+         unsigned int uid;
+         unsigned int gid;
+         unsigned int gids<16>;
+      };
+
+   The "stamp" is an arbitrary ID which the caller machine may generate.
+   The "machinename" is the name of the caller's machine (like
+   "krypton").  The "uid" is the caller's effective user ID.  The "gid"
+   is the caller's effective group ID.  The "gids" is a counted array of
+   groups which contain the caller as a member.  The verifier
+   accompanying the credential should have "AUTH_NONE" flavor value
+   (defined above).  Note this credential is only unique within a
+   particular domain of machine names, uids, and gids.
+
+   The flavor value of the verifier received in the reply message from
+   the server may be "AUTH_NONE" or "AUTH_SHORT".  In the case of
+   "AUTH_SHORT", the bytes of the reply verifier's string encode an
+   opaque structure.  This new opaque structure may now be passed to the
+   server instead of the original "AUTH_SYS" flavor credential.  The
+   server may keep a cache which maps shorthand opaque structures
+   (passed back by way of an "AUTH_SHORT" style reply verifier) to the
+   original credentials of the caller.  The caller can save network
+   bandwidth and server cpu cycles by using the shorthand credential.
+
+   The server may flush the shorthand opaque structure at any time.  If
+   this happens, the remote procedure call message will be rejected due
+   to an authentication error.  The reason for the failure will be
+   "AUTH_REJECTEDCRED".  At this point, the client may wish to try the
+   original "AUTH_SYS" style of credential.
+
+   It should be noted that use of this flavor of authentication does not
+   guarantee any security for the users or providers of a service, in
+   itself.  The authentication provided by this scheme can be considered
+   legitimate only when applications using this scheme and the network
+   can be secured externally, and privileged transport addresses are
+   used for the communicating end-points (an example of this is the use
+   of privileged TCP/UDP ports in Unix systems - note that not all
+   systems enforce privileged transport address mechanisms).
+
+
+
+Srinivasan                  Standards Track                    [Page 16]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+REFERENCES
+
+   [1]  Birrell, A. D.  & Nelson, B. J., "Implementing Remote Procedure
+        Calls", XEROX CSL-83-7, October 1983.
+
+   [2]  Cheriton, D., "VMTP: Versatile Message Transaction Protocol",
+        Preliminary Version 0.3, Stanford University, January 1987.
+
+   [3]  Diffie & Hellman, "New Directions in Cryptography", IEEE
+        Transactions on Information Theory IT-22, November 1976.
+
+   [4]  Mills, D., "Network Time Protocol", RFC 1305, UDEL,
+        March 1992.
+
+   [5]  National Bureau of Standards, "Data Encryption Standard",
+        Federal Information Processing Standards Publication 46, January
+        1977.
+
+   [6]  Postel, J., "Transmission Control Protocol - DARPA Internet
+        Program Protocol Specification", STD 7, RFC 793, USC/Information
+        Sciences Institute, September 1981.
+
+   [7]  Postel, J., "User Datagram Protocol", STD 6, RFC 768,
+        USC/Information Sciences Institute, August 1980.
+
+   [8]  Reynolds, J., and Postel, J., "Assigned Numbers", STD 2,
+        RFC 1700, USC/Information Sciences Institute, October 1994.
+
+   [9]  Srinivasan, R., "XDR: External Data Representation Standard",
+        RFC 1832, Sun Microsystems, Inc., August 1995.
+
+   [10] Miller, S., Neuman, C., Schiller, J., and  J. Saltzer, "Section
+        E.2.1: Kerberos  Authentication and Authorization System",
+        M.I.T. Project Athena, Cambridge, Massachusetts, December 21,
+        1987.
+
+   [11] Steiner, J., Neuman, C., and J. Schiller, "Kerberos: An
+        Authentication Service for Open Network Systems", pp. 191-202 in
+        Usenix Conference Proceedings, Dallas, Texas, February 1988.
+
+   [12] Kohl, J. and C. Neuman, "The Kerberos Network Authentication
+        Service (V5)", RFC 1510, Digital Equipment Corporation,
+        USC/Information Sciences Institute, September 1993.
+
+
+
+
+
+
+
+
+Srinivasan                  Standards Track                    [Page 17]
+
+RFC 1831        Remote Procedure Call Protocol Version 2     August 1995
+
+
+Security Considerations
+
+   Security issues are not discussed in this memo.
+
+Author's Address
+
+   Raj Srinivasan
+   Sun Microsystems, Inc.
+   ONC Technologies
+   2550 Garcia Avenue
+   M/S MTV-5-40
+   Mountain View, CA  94043
+   USA
+
+   Phone: 415-336-2478
+   Fax:   415-336-6015
+   EMail: raj@eng.sun.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Srinivasan                  Standards Track                    [Page 18]
+