rfc1831.txt

RFC 的详细文档！


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 [e-mail]
       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 [e-mail] 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 "[e-mail]".  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
   "[e-mail]".  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