rfc1050.txt

<VC++网络游戏建摸与实现>源代码

Sun Microsystems, Inc.                                          [Page 6]

RFC 1050                 Remote Procedure Call                April 1988


   The first group is a range of numbers administered by Sun
   Microsystems 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.  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.
   That is, each call message is matched with a response message.
   However, the protocol itself is a message-passing protocol with which
   other (non-RPC) protocols can be implemented.  Sun currently uses, or
   perhaps abuses, the RPC message protocol for the following two (non-
   RPC) protocols:  batching (or pipelining) and broadcast RPC.  These
   two protocols are discussed but not defined below.

7.4.1 Batching

   Batching allows a client to send an arbitrarily large sequence of
   call messages to a server; batching typically uses reliable byte
   stream protocols (like TCP/IP) 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 requests.  A sequence of batch
   calls is usually terminated by a legitimate RPC in order to flush the
   pipeline (with positive acknowledgement).

7.4.2 Broadcast RPC

   In broadcast RPC-based protocols, the client sends a broadcast packet
   to the network and waits for numerous replies.  Broadcast RPC uses
   unreliable, packet-based protocols (like UDP/IP) as its transports.
   Servers that support broadcast protocols only respond when the
   request is successfully processed, and are silent in the face of
   errors.  Broadcast RPC uses the Port Mapper RPC service to achieve
   its semantics.  (See Appendix A for more information.)

8. THE RPC MESSAGE PROTOCOL

   This section defines the RPC message protocol in the XDR data
   description language.  The message is defined in a top-down style.

       enum msg_type {
          CALL  = 0,
          REPLY = 1
       };



Sun Microsystems, Inc.                                          [Page 7]

RFC 1050                 Remote Procedure Call                April 1988


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

       /*
        * 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_BADCRED      = 1,  /* bad credentials (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 */
       };

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



Sun Microsystems, Inc.                                          [Page 8]

RFC 1050                 Remote Procedure Call                April 1988


        * 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 request 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 credentials)
        * 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.
        */
       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 request:
        * The call message was either accepted or rejected.
        */
       union reply_body switch (reply_stat stat) {
       case MSG_ACCEPTED:
          accepted_reply areply;
       case MSG_DENIED:
          rejected_reply rreply;
       } reply;

       /*



Sun Microsystems, Inc.                                          [Page 9]

RFC 1050                 Remote Procedure Call                April 1988


        * Reply to an RPC request that was accepted by the server:
        * there could be an error even though the request was accepted.
        * The first field is an authentication verifier that the server
        * generates in order to validate itself to the caller.  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, and GARBAGE_ARGS
        * 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,
               * and GARBAGE_ARGS.
               */
              void;
           } reply_data;
       };

       /*
        * Reply to an RPC request that was rejected by the server:
        * The request can be rejected for two reasons:  either the
        * server is not running a compatible version of the RPC
        * protocol (RPC_MISMATCH), or the server refuses to
        * authenticate 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 refused
        * authentication, failure status is returned.
        */
       union rejected_reply switch (reject_stat stat) {
       case RPC_MISMATCH:
          struct {
             unsigned int low;
             unsigned int high;



Sun Microsystems, Inc.                                         [Page 10]

RFC 1050                 Remote Procedure Call                April 1988


          } 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
   some "flavors" of authentication implemented at (and supported by)
   Sun.  Other sites are free to invent new authentication types, with
   the same rules of flavor number assignment as there is for program
   number assignment.

9.1 Null Authentication

   Often calls must be made where the caller does not know who he is or
   the server does not care who the caller is.  In this case, the flavor
   value (the discriminant of the opaque_auth's union) of the RPC
   message's credentials, verifier, and response verifier is
   "AUTH_NULL".  The bytes of the opaque_auth's body are undefined.  It
   is recommended that the opaque length be zero.

9.2 UNIX Authentication

   The caller of a remote procedure may wish to identify himself as he
   is identified on a UNIX(tm) system.  The value of the credential's
   discriminant of an RPC call message is "AUTH_UNIX".  The bytes of the
   credential's opaque body encode the the following structure:

         struct auth_unix {
            unsigned int stamp;
            string machinename<255>;
            unsigned int uid;
            unsigned int gid;
            unsigned int gids<10>;
         };

   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 credentials should be of "AUTH_NULL" (defined
   above).

   The value of the discriminant of the response verifier received in
   the reply message from the server may be "AUTH_NULL" or "AUTH_SHORT".



Sun Microsystems, Inc.                                         [Page 11]

RFC 1050                 Remote Procedure Call                April 1988


   In the case of "AUTH_SHORT", the bytes of the response verifier's
   string encode an opaque structure.  This new opaque structure may now
   be passed to the server instead of the original "AUTH_UNIX" flavor
   credentials.  The server keeps a cache which maps shorthand opaque
   structures (passed back by way of an "AUTH_SHORT" style response
   verifier) to the original credentials of the caller.  The caller can
   save network bandwidth and server cpu cycles by using the new
   credentials.

   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 caller may wish to try the
   original "AUTH_UNIX" style of credentials.

9.3 DES Authentication

   UNIX authentication suffers from two major problems:

         (1) The naming is too UNIX oriented.
         (2) There is no verifier, so credentials can easily be faked.

   DES authentication attempts to fix these two problems.

9.3.1 Naming

   The first problem is handled by addressing the caller by a simple
   string of characters instead of by an operating system specific
   integer.  This string of characters is known as the "netname" or
   network name of the caller.  The server is not allowed to interpret
   the contents of the caller's name in any other way except to identify
   the caller.  Thus, netnames should be unique for every caller in the
   Internet.

   It is up to each operating system's implementation of DES
   authentication to generate netnames for its users that insure this
   uniqueness when they call upon remote servers.  Operating systems
   already know how to distinguish users local to their systems.  It is
   usually a simple matter to extend this mechanism to the network.  For
   example, a UNIX user at Sun with a user ID of 515 might be assigned
   the following netname: "[e-mail]".  This netname contains
   three items that serve to insure it is unique.  Going backwards,
   there is only one naming domain called "sun.com" in the Internet.
   Within this domain, there is only one UNIX user with user ID 515.
   However, there may be another user on another operating system, for
   example VMS, within the same naming domain that, by coincidence,
   happens to have the same user ID.  To insure that these two users can
   be distinguished, we add the operating system name.  So, one user is



Sun Microsystems, Inc.                                         [Page 12]