rfc1057.txt

著名的RFC文档,其中有一些文档是已经翻译成中文的的.

   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.
   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.  Sun
   currently uses, or perhaps abuses, the RPC message protocol for the
   batching (or pipelining) and broadcast remote procedure calls.

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



Sun Microsystems                                                [Page 7]

RFC 1057            Remote Procedure Call, Version 2           June 1988


   that support broadcast protocols only respond when the call is
   successfully processed, and are silent in the face of errors.
   Broadcast calls use the Port Mapper RPC service to achieve their
   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 [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   */
         };

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












Sun Microsystems                                                [Page 8]

RFC 1057            Remote Procedure Call, Version 2           June 1988


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











Sun Microsystems                                                [Page 9]

RFC 1057            Remote Procedure Call, Version 2           June 1988


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






















Sun Microsystems                                               [Page 10]

RFC 1057            Remote Procedure Call, Version 2           June 1988


         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 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 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;
            } mismatch_info;
         case AUTH_ERROR:
            auth_stat stat;
         };











Sun Microsystems                                               [Page 11]

RFC 1057            Remote Procedure Call, Version 2           June 1988


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 client does not know its identity
   or the server does not care who the client is.  In this case, the
   flavor value (the discriminant of the opaque_auth's union) of the RPC
   message's credentials, verifier, and reply 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 client may wish to identify itself as it 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<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 credentials should be of "AUTH_NULL" (defined
   above).  Note these credentials are only unique within a particular
   domain of machine names, uids, and gids.  Inter-domain naming is
   beyond the scope of this document.

   The value of the discriminant of the reply verifier received in the
   reply message from the server may be "AUTH_NULL" 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_UNIX" flavor



Sun Microsystems                                               [Page 12]

RFC 1057            Remote Procedure Call, Version 2           June 1988


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

9.3 DES Authentication

   UNIX authentication suffers from three major problems:

   (1) The naming is too UNIX oriented.
   (2) There is no universal name, uid, and gid space.
   (3) There is no verifier, so credentials can easily be faked.

   DES authentication attempts to address these problems.

9.3.1 Naming

   The first problem is handled by addressing the client 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 client. The server is not allowed to interpret