doc: Add RFC documents

1 files changed, 1347 insertions, 0 deletions

diff --git a/doc/rfc/rfc1050.txt b/doc/rfc/rfc1050.txt
new file mode 100644
index 0000000..307c581
--- /dev/null
+++ b/doc/rfc/rfc1050.txt
@@ -0,0 +1,1347 @@
+
+
+
+
+
+
+Network Working Group                             Sun Microsystems, Inc.
+Request for Comments: 1050                        April 1988
+
+
+
+                       RPC: Remote Procedure Call
+                         Protocol Specification
+
+STATUS OF THIS MEMO
+
+   This RFC describes a standard that Sun Microsystems and others are
+   using and is one we wish to propose for the Internet's consideration.
+   This memo is not an Internet standard at this time.  Distribution of
+   this memo is unlimited.
+
+1. INTRODUCTION
+
+   This document specifies a message protocol used in implementing Sun's
+   Remote Procedure Call (RPC) package.  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 RPC or its uses.  The paper by Birrell and
+   Nelson [1] is recommended as an excellent background to and
+   justification of RPC.
+
+2. TERMINOLOGY
+
+   This document discusses servers, services, programs, procedures,
+   clients, and versions.  A server is a piece of software where network
+   services are implemented.  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 (see
+   Appendix A for an example).  Network clients are pieces of software
+   that initiate remote procedure calls to services.  A server may
+   support more than one version of a remote program in order to be
+   forward 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
+   IO and have procedures like "read" and "write".  A client machine of
+   the network file service would call the procedures associated with
+   the two programs of the service on behalf of some user on the client
+   machine.
+
+
+
+
+
+
+Sun Microsystems, Inc.                                          [Page 1]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+3. THE RPC MODEL
+
+   The remote procedure call model 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 result
+   register).  It then transfers control to the procedure, and
+   eventually gains back control.  At that point, the results of the
+   procedure are extracted from the well-specified location, and the
+   caller continues execution.
+
+   The remote procedure call is similar, in that one thread of control
+   logically winds through two processes -- one is the caller's process,
+   the other is a server's process.  That is, the caller process sends a
+   call message to the server process and waits (blocks) for a reply
+   message.  The call message contains the procedure's parameters, among
+   other things.  The reply message contains the procedure's results,
+   among other things.  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.
+
+   Note that 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 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 task to process an
+   incoming request, so that the server can be free to receive other
+   requests.
+
+4. TRANSPORTS AND SEMANTICS
+
+   The RPC protocol is independent of transport protocols.  That is, RPC
+   does not care how a message is passed from one process to another.
+   The protocol deals only with specification and interpretation of
+   messages.
+
+   It is important to point out that RPC does not try to implement any
+   kind of reliability and that the application must 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/IP [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/IP [7], it must implement
+   its own retransmission and time-out policy as the RPC layer does not
+
+
+
+Sun Microsystems, Inc.                                          [Page 2]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+   provide this service.
+
+   Because of transport independence, the RPC protocol does not attach
+   specific semantics to the remote procedures or their execution.
+   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/IP.  If an
+   application retransmits RPC messages after short time-outs, the only
+   thing it can infer if it receives no reply is that the procedure was
+   executed zero or more times.  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
+   request.  The main use of this transaction is by the client RPC layer
+   in matching replies to requests.  However, a client application may
+   choose to reuse its previous transaction ID when retransmitting a
+   request.  The server application, knowing this fact, may choose to
+   remember this ID after granting a request and not regrant requests
+   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/IP, the
+   application can infer from a reply message that the procedure was
+   executed exactly once, but if it receives no reply message, it cannot
+   assume 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 the most natural transport for RPC.
+
+   Note:  At Sun, RPC is currently implemented on top of both TCP/IP and
+   UDP/IP transports.
+
+5. BINDING AND RENDEZVOUS INDEPENDENCE
+
+   The act of binding a client to a service is NOT part of the remote
+   procedure call specification.  This important and necessary function
+   is left up to some higher-level software.  (The software may use RPC
+   itself; see Appendix A.)
+
+   Implementors should think of the RPC protocol as the jump-subroutine
+   instruction ("JSR") of a network; the loader (binder) makes JSR
+
+
+
+Sun Microsystems, Inc.                                          [Page 3]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+   useful, and the loader itself uses JSR to accomplish its task.
+   Likewise, the network makes RPC useful, 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.  Security and access
+   control mechanisms can be built on top of the 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.
+
+   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 fields:  remote program
+   number, remote program version number, and remote procedure number.
+   The three fields uniquely identify the procedure to be called.
+   Program numbers are administered by some central authority (like
+   Sun).  Once an implementor has a program number, he can implement his
+   remote program; the first implementation would most likely have the
+   version number of 1.  Because most new protocols evolve into better,
+   stable, and mature protocols, a version field of the call message
+   identifies which version of the protocol the caller is using.
+   Version numbers make speaking old and new protocols through the same
+   server process possible.
+
+
+
+
+Sun Microsystems, Inc.                                          [Page 4]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+   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 speak 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 caller 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.)
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sun Microsystems, Inc.                                          [Page 5]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+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 credentials 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:
+
+         enum auth_flavor {
+            AUTH_NULL       = 0,
+            AUTH_UNIX       = 1,
+            AUTH_SHORT      = 2,
+            AUTH_DES        = 3
+            /* and more to be defined */
+         };
+
+         struct opaque_auth {
+            auth_flavor flavor;
+            opaque body<400>;
+         };
+
+   In simple English, any "opaque_auth" structure is an "auth_flavor"
+   enumeration followed by bytes which are opaque to 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 response 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 Sun
+          20000000 - 3fffffff   defined by user
+          40000000 - 5fffffff   transient
+          60000000 - 7fffffff   reserved
+          80000000 - 9fffffff   reserved
+          a0000000 - bfffffff   reserved
+          c0000000 - dfffffff   reserved
+          e0000000 - ffffffff   reserved
+
+
+
+
+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: "unix.515@sun.com".  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]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+   "unix.515@sun.com" and the other is "vms.515@sun.com".
+
+   The first field is actually a naming method rather than an operating
+   system name.  It just happens that today, there is almost a one-to-
+   one correspondence between naming methods and operating systems.  If
+   the world could agree on a naming standard, the first field could be
+   the name of that standard, instead of an operating system name.
+
+9.3.2 DES Authentication Verifiers
+
+   Unlike UNIX authentication, DES authentication does have a verifier
+   so the server can validate the client's credential (and vice-versa).
+   The contents of this verifier is primarily an encrypted timestamp.
+   The server can decrypt this timestamp, and if it is close to what the
+   real time is, then the client must have encrypted it correctly.  The
+   only way the client could encrypt it correctly is to know the
+   "conversation key" of the RPC session.  And, if the client knows the
+   conversation key, then it must be the real client.
+
+   The conversation key is a DES [5] key which the client generates and
+   notifies the server of in its first RPC call.  The conversation key
+   is encrypted using a public key scheme in this first transaction.
+   The particular public key scheme used in DES authentication is
+   Diffie-Hellman [3], with 128-bit keys.  The details of this
+   encryption method are described later.
+
+   The client and the server need the same notion of the current time in
+   order for all of this to work.  If network time synchronization
+   cannot be guaranteed, then client can synchronize with the server
+   before beginning the conversation, perhaps by consulting the Internet
+   Time Server (TIME [4]).
+
+   The way a server determines if a client timestamp is valid is
+   somewhat complicated.  For any other transaction but the first, the
+   server just checks for two things:
+
+         (1) the timestamp is greater than the one previously seen from
+             the same client.
+
+         (2) the timestamp has not expired.
+
+   A timestamp is expired if the server's time is later than the sum of
+   the client's timestamp, plus what is known as the client's "window".
+   The "window" is a number the client passes (encrypted) to the server
+   in its first transaction.  You can think of it as a lifetime for the
+   credential.
+
+   This explains everything but the first transaction.  In the first
+
+
+
+Sun Microsystems, Inc.                                         [Page 13]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+   transaction, the server checks only that the timestamp has not
+   expired.  If this was all that was done though, then it would be
+   quite easy for the client to send random data in place of the
+   timestamp with a fairly good chance of succeeding.  As an added
+   check, the client sends an encrypted item in the first transaction
+   known as the "window verifier" which must be equal to the window
+   minus 1, or the server will reject the credential.
+
+   The client too, must check the verifier returned from the server to
+   be sure it is legitimate.  The server sends back to the client the
+   encrypted timestamp it received from the client, minus one second.
+   If the client gets anything different than this, it will reject it.
+
+9.3.3 Nicknames and Clock Synchronization
+
+   After the first transaction, the server's DES authentication
+   subsystem returns in its verifier to the client an integer "nickname"
+   which the client may use in its further transactions instead of
+   passing its netname, encrypted DES key, and window every time. The
+   nickname is most likely an index into a table on the server which
+   stores for each client its netname, decrypted DES key, and window.
+
+   Though they originally were synchronized, the client's and server's
+   clocks can get out of sync again.  When this happens, the client RPC
+   subsystem most likely will get back "RPC_AUTHERROR" at which point it
+   should resynchronize.
+
+   A client may still get the "RPC_AUTHERROR" error even though it is
+   synchronized with the server.  The reason is that the server's
+   nickname table is a limited size, and it may flush entries whenever
+   it wants.  A client should resend its original credential in this
+   case and the server will give it a new nickname.  If a server
+   crashes, the entire nickname table gets flushed, and all clients will
+   have to resend their original credentials.
+
+9.3.4 DES Authentication Protocol Specification (in XDR language)
+
+    /*
+     * There are two kinds of credentials: one in which the client uses
+     * its full network name, and one in which it uses its "nickname"
+     * (just an unsigned integer) given to it by the server.  The
+     * client must use its fullname in its first transaction with the
+     * server, in which the server will return to the client its
+     * nickname.  The client may use its nickname in all further
+     * transactions with the server.  There is no requirement to use the
+     * nickname, but it is wise to use it for performance reasons.
+     */
+    enum authdes_namekind {
+
+
+
+Sun Microsystems, Inc.                                         [Page 14]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+       ADN_FULLNAME = 0,
+       ADN_NICKNAME = 1
+    };
+
+    /*
+     * A 64-bit block of encrypted DES data
+     */
+    typedef opaque des_block[8];
+
+    /*
+     * Maximum length of a network user's name
+     */
+    const MAXNETNAMELEN = 255;
+
+    /*
+     * A fullname contains the network name of the client, an encrypted
+     * conversation key, and the window.  The window is actually a
+     * lifetime for the credential.  If the time indicated in the
+     * verifier timestamp plus the window has past, then the server
+     * should expire the request and not grant it.  To insure that
+     * requests are not replayed, the server should insist that
+     * timestamps are greater than the previous one seen, unless it is
+     * the  first transaction.  In the first transaction, the server
+     * checks instead that the window verifier is one less than the
+     * window.
+     */
+    struct authdes_fullname {
+       string name<MAXNETNAMELEN>;  /* name of client                */
+       des_block key;               /* PK encrypted conversation key */
+       unsigned int window;         /* encrypted window              */
+    };
+
+    /*
+     * A credential is either a fullname or a nickname
+     */
+    union authdes_cred switch (authdes_namekind adc_namekind) {
+    case ADN_FULLNAME:
+       authdes_fullname adc_fullname;
+    case ADN_NICKNAME:
+       unsigned int adc_nickname;
+    };
+
+    /*
+     * A timestamp encodes the time since midnight, January 1, 1970.
+     */
+    struct timestamp {
+         unsigned int seconds;    /* seconds          */
+         unsigned int useconds;   /* and microseconds */
+
+
+
+Sun Microsystems, Inc.                                         [Page 15]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+    };
+
+    /*
+     * Verifier: client variety
+     * The window verifier is only used in the first transaction.  In
+     * conjunction with a fullname credential, these items are packed
+     * into the following structure before being encrypted:
+     *
+     * struct {
+     *     adv_timestamp;        -- one DES block
+     *     adc_fullname.window;  -- one half DES block
+     *     adv_winverf;          -- one half DES block
+     * }
+     * This structure is encrypted using CBC mode encryption with an
+     * input vector of zero.  All other encryptions of timestamps use
+     * ECB mode encryption.
+     */
+    struct authdes_verf_clnt {
+       timestamp adv_timestamp;    /* encrypted timestamp       */
+       unsigned int adv_winverf;   /* encrypted window verifier */
+    };
+
+    /*
+     * Verifier: server variety
+     * The server returns (encrypted) the same timestamp the client
+     * gave it minus one second.  It also tells the client its nickname
+     * to be used in future transactions (unencrypted).
+     */
+    struct authdes_verf_svr {
+       timestamp adv_timeverf;     /* encrypted verifier      */
+       unsigned int adv_nickname;  /* new nickname for client */
+    };
+
+9.3.5 Diffie-Hellman Encryption
+
+   In this scheme, there are two constants "PROOT" and "MODULUS".  The
+   particular values Sun has chosen for these for the DES authentication
+   protocol are:
+
+        const PROOT = 2;
+        const MODULUS = "b520985fb31fcaf75036701e37d8b857"; /* in hex */
+
+   The way this scheme works is best explained by an example.  Suppose
+   there are two people "A" and "B" who want to send encrypted messages
+   to each other.  So, A and B both generate "secret" keys at random
+   which they do not reveal to anyone.  Let these keys be represented as
+   SK(A) and SK(B).  They also publish in a public directory their
+   "public" keys.  These keys are computed as follows:
+
+
+
+Sun Microsystems, Inc.                                         [Page 16]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+            PK(A) = ( PROOT ** SK(A) ) mod MODULUS
+            PK(B) = ( PROOT ** SK(B) ) mod MODULUS
+
+   The "**" notation is used here to represent exponentiation.  Now,
+   both A and B can arrive at the "common" key between them, represented
+   here as CK(A, B), without revealing their secret keys.
+
+         A computes:
+
+            CK(A, B) = ( PK(B) ** SK(A)) mod MODULUS
+
+         while B computes:
+
+            CK(A, B) = ( PK(A) ** SK(B)) mod MODULUS
+
+         These two can be shown to be equivalent:
+
+            (PK(B) ** SK(A)) mod MODULUS = (PK(A) ** SK(B)) mod MODULUS
+
+         We drop the "mod MODULUS" parts and assume modulo arithmetic to
+         simplify things:
+
+            PK(B) ** SK(A) = PK(A) ** SK(B)
+
+         Then, replace PK(B) by what B computed earlier and likewise for
+         PK(A).
+
+            ((PROOT ** SK(B)) ** SK(A) = (PROOT ** SK(A)) ** SK(B)
+
+         which leads to:
+
+            PROOT ** (SK(A) * SK(B)) = PROOT ** (SK(A) * SK(B))
+
+   This common key CK(A, B) is not used to encrypt the timestamps used
+   in the protocol.  Rather, it is used only to encrypt a conversation
+   key which is then used to encrypt the timestamps.  The reason for
+   doing this is to use the common key as little as possible, for fear
+   that it could be broken.  Breaking the conversation key is a far less
+   serious offense, since conversations are relatively short-lived.
+
+   The conversation key is encrypted using 56-bit DES keys, yet the
+   common key is 128 bits.  To reduce the number of bits, 56 bits are
+   selected from the common key as follows.  The middle-most 8-bytes are
+   selected from the common key, and then parity is added to the lower
+   order bit of each byte, producing a 56-bit key with 8 bits of parity.
+
+
+
+
+
+
+Sun Microsystems, Inc.                                         [Page 17]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+10. RECORD MARKING STANDARD
+
+   When RPC messages are passed on top of a byte stream protocol (like
+   TCP/IP), it is necessary, or at least desirable, to delimit one
+   message from another in order to detect and possibly recover from
+   user protocol errors.  This is called record marking (RM).  Sun uses
+   this RM/TCP/IP transport for passing RPC messages on TCP streams.
+   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.  We use the RPC
+   Language for this purpose.  It is an extension to the XDR language.
+   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:
+
+         /*
+          * Simple ping program
+          */
+         program PING_PROG {
+            /*
+             * Latest and greatest version
+             */
+            version PING_VERS_PINGBACK {
+               void
+               PINGPROC_NULL(void) = 0;
+
+               /*
+                * Ping the caller, return the round-trip time
+                * (in microseconds).  Returns -1 if the operation
+                * timed out.
+
+
+
+Sun Microsystems, Inc.                                         [Page 18]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+                */
+               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.1 The RPC Language Specification
+
+   The RPC language is identical to the XDR language, except for the
+   added definition of a "program-def" described below.
+
+      program-def:
+         "program" identifier "{"
+             version-def
+             version-def *
+         "}" "=" constant ";"
+
+      version-def:
+         "version" identifier "{"
+             procedure-def
+             procedure-def *
+         "}" "=" constant ";"
+
+      procedure-def:
+
+
+
+Sun Microsystems, Inc.                                         [Page 19]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+         type-specifier identifier "(" type-specifier ")"
+         "=" constant ";"
+
+11.2 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.
+
+APPENDIX A: PORT MAPPER PROGRAM PROTOCOL
+
+   The port mapper program maps RPC program and version numbers to
+   transport-specific port numbers.  This program makes dynamic binding
+   of remote programs possible.
+
+   This is desirable because the range of reserved port numbers is very
+   small, and the number of potential remote programs is very large.  By
+   running only the port mapper on a reserved port, the port numbers of
+   other remote programs can be ascertained by querying the port mapper.
+
+   The port mapper also aids in broadcast RPC.  A given RPC program will
+   usually have different port number bindings on different machines, so
+   there is no way to directly broadcast to all of these programs.  The
+   port mapper, however, does have a fixed port number.  So, to
+   broadcast to a given program, the client actually sends its message
+   to the port mapper located at the broadcast address.  Each port
+   mapper that picks up the broadcast then calls the local service
+   specified by the client.  When the port mapper gets the reply from
+   the local service, it sends the reply on back to the client.
+
+A.1 Port Mapper Protocol Specification (in RPC Language)
+
+
+      const PMAP_PORT = 111;      /* portmapper port number */
+
+
+
+
+Sun Microsystems, Inc.                                         [Page 20]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+      /*
+       * A mapping of (program, version, protocol) to port number
+       */
+      struct mapping {
+         unsigned int prog;
+         unsigned int vers;
+         unsigned int prot;
+         unsigned int port;
+      };
+
+      /*
+       * Supported values for the "prot" field
+       */
+      const IPPROTO_TCP = 6;      /* protocol number for TCP/IP */
+      const IPPROTO_UDP = 17;     /* protocol number for UDP/IP */
+
+      /*
+       * A list of mappings
+       */
+      struct *pmaplist {
+         mapping map;
+         pmaplist next;
+      };
+      /*
+       * Arguments to callit
+       */
+      struct call_args {
+         unsigned int prog;
+         unsigned int vers;
+         unsigned int proc;
+         opaque args<>;
+      };
+      /*
+       * Results of callit
+       */
+      struct call_result {
+         unsigned int port;
+         opaque res<>;
+      };
+
+     /*
+      * Port mapper procedures
+      */
+      program PMAP_PROG {
+         version PMAP_VERS {
+            void
+            PMAPPROC_NULL(void)         = 0;
+
+
+
+
+Sun Microsystems, Inc.                                         [Page 21]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+            bool
+            PMAPPROC_SET(mapping)       = 1;
+
+            bool
+            PMAPPROC_UNSET(mapping)     = 2;
+
+            unsigned int
+            PMAPPROC_GETPORT(mapping)   = 3;
+
+            pmaplist
+            PMAPPROC_DUMP(void)         = 4;
+
+            call_result
+            PMAPPROC_CALLIT(call_args)  = 5;
+         } = 2;
+      } = 100000;
+
+A.2 Port Mapper Operation
+
+   The portmapper program currently supports two protocols (UDP/IP and
+   TCP/IP).  The portmapper is contacted by talking to it on assigned
+   port number 111 (SUNRPC [8]) on either of these protocols.  The
+   following is a description of each of the portmapper procedures:
+
+      PMAPPROC_NULL:
+
+         This procedure does no work.  By convention, procedure zero of
+         any protocol takes no parameters and returns no results.
+
+      PMAPPROC_SET:
+
+         When a program first becomes available on a machine, it
+         registers itself with the port mapper program on the same
+         machine.  The program passes its program number "prog", version
+         number "vers", transport protocol number "prot", and the port
+         "port" on which it awaits service request.  The procedure
+         returns a boolean response whose value is "TRUE" if the
+         procedure successfully established the mapping and "FALSE"
+         otherwise.  The procedure refuses to establish a mapping if one
+         already exists for the tuple "(prog, vers, prot)".
+
+      PMAPPROC_UNSET:
+
+         When a program becomes unavailable, it should unregister itself
+         with the port mapper program on the same machine.  The
+         parameters and results have meanings identical to those of
+         "PMAPPROC_SET".  The protocol and port number fields of the
+         argument are ignored.
+
+
+
+Sun Microsystems, Inc.                                         [Page 22]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+      PMAPPROC_GETPORT:
+
+         Given a program number "prog", version number "vers", and
+         transport protocol number "prot", this procedure returns the
+         port number on which the program is awaiting call requests.  A
+         port value of zeros means the program has not been registered.
+         The "port" field of the argument is ignored.
+
+      PMAPPROC_DUMP:
+
+         This procedure enumerates all entries in the port mapper's
+         database.  The procedure takes no parameters and returns a list
+         of program, version, protocol, and port values.
+
+      PMAPPROC_CALLIT:
+
+         This procedure allows a caller to call another remote procedure
+         on the same machine without knowing the remote procedure's port
+         number.  It is intended for supporting broadcasts to arbitrary
+         remote programs via the well-known port mapper's port.  The
+         parameters "prog", "vers", "proc", and the bytes of "args" are
+         the program number, version number, procedure number, and
+         parameters of the remote procedure.  Note:
+
+            (1) This procedure only sends a response if the procedure
+                 was successfully executed and is silent (no response)
+                 otherwise.
+
+            (2) The port mapper communicates with the remote program
+                using UDP/IP only.
+
+         The procedure returns the remote program's port number, and the
+         bytes of results are the results of the remote procedure.
+
+REFERENCES
+
+   [1]  Birrel, A. D., and Nelson, B. J., "Implementing Remote
+        Procedure Calls", XEROX CSL-83-7, October 1983.
+
+   [2]  Cheriton, D., "VMTP: Versatile Message Transaction Protocol",
+        Version 0.7, RFC-1045, Stanford University, February 1988.
+
+   [3]  Diffie & Hellman, "Net Directions in Cryptography", IEEE
+        Transactions on Information Theory IT-22, November 1976.
+
+   [4]  Postel, J., and Harrenstien, K., "Time Protocol", RFC-868,
+        Network Information Center, SRI, May 1983.
+
+
+
+
+Sun Microsystems, Inc.                                         [Page 23]
+
+RFC 1050                 Remote Procedure Call                April 1988
+
+
+   [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", RFC-793; Network Information
+        Center, SRI, September 1981.
+
+   [7]  Postel, J., "User Datagram Protocol", RFC-768, Network
+        Information Center, SRI, August 1980.
+
+   [8]  Reynolds, J. and Postel, J.; "Assigned Numbers", RFC-1010,
+        Network Information Center, SRI, May 1987.
+
+   [9]  Sun Microsystems; "XDR:  External Data Representation
+        Standard", RFC-1014; Sun Microsystems, June 1987.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Sun Microsystems, Inc.                                         [Page 24]
+
\ No newline at end of file