rfc1831.html

this gives details of the network programming

   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.

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

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 <A HREF="mailto:[e-mail]">[e-mail]</A>
       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 <A HREF="mailto:[e-mail]">[e-mail]</A> 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 "<A HREF="mailto:[e-mail]">[e-mail]</A>".  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

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

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

   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:
             /*

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