home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_ietf_j_p / draft-ietf-oncrpc-remote-02.txt < prev    next >
Text File  |  1996-08-30  |  37KB  |  1,194 lines
  1.  
  2.  
  3. INTERNET-DRAFT                                         Stephen X. Nahm
  4. August 28, 1996                                        Sun Microsystems
  5.  
  6.         RPC: Remote Procedure Call Protocol Specification Version 2
  7.  
  8.                       draft-ietf-oncrpc-remote-02.txt
  9.  
  10.  
  11. ABSTRACT
  12.  
  13. This document describes the ONC Remote Procedure Call (ONC RPC Version 2)
  14. protocol as it is currently deployed and accepted.  "ONC" stands for "Open
  15. Network Computing".
  16.  
  17. STATUS OF THIS MEMO
  18.  
  19. This document is an Internet-Draft.  Internet-Drafts are working documents
  20. of the Internet Engineering Task Force (IETF), its areas, and its working
  21. groups.  Note that other groups may also distribute working documents as
  22. Internet-Drafts.
  23.  
  24. Internet-Drafts are draft documents valid for a maximum of six months.
  25. This Internet-Draft expires on February 28, 1996.  Internet-Drafts may be
  26. updated, replaced, or obsoleted by other documents at any time. It is not
  27. appropriate to use Internet-Drafts as reference material or to cite them
  28. other than as "work in progress."
  29.  
  30. To learn the current status of any Internet-Draft, please check the "1id-
  31. abstracts.txt" listing contained in the Internet-Drafts Shadow Directories
  32. on ftp.is.co.za (Africa), nic.nordu.net (Europe), munnari.oz.au (Pacific
  33. Rim), ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast).
  34.  
  35. Distribution of this memo is unlimited.
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59. Expires: February 28, 1996                                 [Page 1]
  60.  
  61.  
  62.  
  63. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  64.  
  65.  
  66. CONTENTS
  67.  
  68.    1. INTRODUCTION
  69.    2. TERMINOLOGY
  70.    3. THE RPC MODEL
  71.    4. TRANSPORTS AND SEMANTICS
  72.    5. BINDING AND RENDEZVOUS INDEPENDENCE
  73.    6. AUTHENTICATION
  74.    7. RPC PROTOCOL REQUIREMENTS
  75.    7.1 RPC Programs and Procedures
  76.    7.2 Authentication
  77.    7.3 Program Number Assignment
  78.    7.4 Other Uses of the RPC Protocol
  79.    7.4.1 Batching
  80.    7.4.2 Broadcast Remote Procedure Calls
  81.    8. THE RPC MESSAGE PROTOCOL
  82.    9. AUTHENTICATION PROTOCOLS
  83.    9.1 Null Authentication
  84.    10. RECORD MARKING STANDARD
  85.    11. THE RPC LANGUAGE
  86.    11.1 An Example Service Described in the RPC Language
  87.    11.2 The RPC Language Specification
  88.    11.3 Syntax Notes
  89.    12. SECURITY CONSIDERATIONS
  90.    13. APPENDIX A: SYSTEM AUTHENTICATION
  91.    14. REFERENCES
  92.    15. AUTHOR'S ADDRESS
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122. Expires: February 28, 1996                                 [Page 2]
  123.  
  124.  
  125.  
  126. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  127.  
  128.  
  129. 1. INTRODUCTION
  130.  
  131. This document specifies version two of the message protocol used in ONC
  132. Remote Procedure Call (RPC).  The message protocol is specified with the
  133. External Data Representation (XDR) language [10].  This document assumes
  134. that the reader is familiar with XDR.  It does not attempt to justify
  135. remote procedure calls systems or describe their use.  The paper by Birrell
  136. and Nelson [1] is recommended as an excellent background for the remote
  137. procedure call concept.
  138.  
  139. 2. TERMINOLOGY
  140.  
  141. This document discusses clients, calls, servers, replies, services,
  142. programs, procedures, and versions.  Each remote procedure call has two
  143. sides: an active client side that makes the call to a server, which sends
  144. back a reply.  A network service is a collection of one or more remote
  145. programs.  A remote program implements one or more remote procedures; the
  146. procedures, their parameters, and results are documented in the specific
  147. program's protocol specification.  A server may support more than one
  148. version of a remote program in order to be compatible with changing
  149. protocols.
  150.  
  151. For example, a network file service may be composed of two programs.  One
  152. program may deal with high-level applications such as file system access
  153. control and locking.  The other may deal with low-level file input and
  154. output and have procedures like "read" and "write".  A client of the
  155. network file service would call the procedures associated with the two
  156. programs of the service on behalf of the client.
  157.  
  158. The terms client and server only apply to a particular transaction; a
  159. particular hardware entity (host) or software entity (process or program)
  160. could operate in both roles at different times.  For example, a program
  161. that supplies remote execution service could also be a client of a network
  162. file service.
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185. Expires: February 28, 1996                                 [Page 3]
  186.  
  187.  
  188.  
  189. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  190.  
  191.  
  192. 3. THE RPC MODEL
  193.  
  194. The ONC RPC protocol is based on the remote procedure call model, which is
  195. similar to the local procedure call model.  In the local case, the caller
  196. places arguments to a procedure in some well- specified location (such as a
  197. register window).  It then transfers control to the procedure, and
  198. eventually regains control.  At that point, the results of the procedure
  199. are extracted from the well- specified location, and the caller continues
  200. execution.
  201.  
  202. The remote procedure call model is similar.  One thread of control
  203. logically winds through two processes: the caller's process, and a server's
  204. process.  The caller process first sends a call message to the server
  205. process and waits (blocks) for a reply message.  The call message includes
  206. the procedure's parameters, and the reply message includes the procedure's
  207. results.  Once the reply message is received, the results of the procedure
  208. are extracted, and caller's execution is resumed.
  209.  
  210. On the server side, a process is dormant awaiting the arrival of a call
  211. message.  When one arrives, the server process extracts the procedure's
  212. parameters, computes the results, sends a reply message, and then awaits
  213. the next call message.
  214.  
  215. In this model, only one of the two processes is active at any given time.
  216. However, this model is only given as an example.  The ONC RPC protocol
  217. makes no restrictions on the concurrency model implemented, and others are
  218. possible.  For example, an implementation may choose to have RPC calls be
  219. asynchronous, so that the client may do useful work while waiting for the
  220. reply from the server.  Another possibility is to have the server create a
  221. separate task to process an incoming call, so that the original server can
  222. be free to receive other requests.
  223.  
  224. There are a few important ways in which remote procedure calls differ from
  225. local procedure calls:
  226.  
  227. 1. Error handling: failures of the remote server or network must be handled
  228. when using remote procedure calls.
  229.  
  230. 2. Global variables and side-effects: since the server does not have access
  231. to the client's address space, hidden arguments cannot be passed as global
  232. variables or returned as side effects.
  233.  
  234. 3. Performance:  remote procedures usually operate one or more orders of
  235. magnitude slower than local procedure calls.
  236.  
  237. 4. Authentication: since remote procedure calls can be transported over
  238. unsecured networks, authentication may be necessary.  Authentication
  239. prevents one entity from masquerading as some other entity.
  240.  
  241. The conclusion is that even though there are tools to automatically
  242. generate client and server libraries for a given service, protocols must
  243. still be designed carefully.
  244.  
  245.  
  246.  
  247.  
  248. Expires: February 28, 1996                                 [Page 4]
  249.  
  250.  
  251.  
  252. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  253.  
  254.  
  255. 4. TRANSPORTS AND SEMANTICS
  256.  
  257. The RPC protocol can be implemented on several different transport
  258. protocols.  The RPC protocol does not care how a message is passed from one
  259. process to another, but only with specification and interpretation of
  260. messages.  However, the application may wish to obtain information about
  261. (and perhaps control over) the transport layer through an interface not
  262. specified in this document.  For example, the transport protocol may impose
  263. a restriction on the maximum size of RPC messages, or it may be stream-
  264. oriented like TCP with no size limit.  The client and server must agree on
  265. their transport protocol choices.
  266.  
  267. It is important to point out that RPC does not try to implement any kind of
  268. reliability and that the application may need to be aware of the type of
  269. transport protocol underneath RPC.  If it knows it is running on top of a
  270. reliable transport such as TCP [6], then most of the work is already done
  271. for it.  On the other hand, if it is running on top of an unreliable
  272. transport such as UDP [7], it must implement its own time-out,
  273. retransmission, and duplicate detection policies as the RPC protocol does
  274. not provide these services.
  275.  
  276. Because of transport independence, the RPC protocol does not attach
  277. specific semantics to the remote procedures or their execution
  278. requirements.  Semantics can be inferred from (but should be explicitly
  279. specified by) the underlying transport protocol.  For example, consider RPC
  280. running on top of an unreliable transport such as UDP.  If an application
  281. retransmits RPC call messages after time- outs, and does not receive a
  282. reply, it cannot infer anything about the number of times the procedure was
  283. executed.  If it does receive a reply, then it can infer that the procedure
  284. was executed at least once.
  285.  
  286. A server may wish to remember previously granted requests from a client and
  287. not regrant them in order to insure some degree of execute-at-most-once
  288. semantics.  A server can do this by taking advantage of the transaction ID
  289. that is packaged with every RPC message.  The main use of this transaction
  290. ID is by the client RPC entity in matching replies to calls.  However, a
  291. client application may choose to reuse its previous transaction ID when
  292. retransmitting a call.  The server may choose to remember this ID after
  293. executing a call and not execute calls with the same ID in order to achieve
  294. some degree of execute-at-most-once semantics.  The server is not allowed
  295. to examine this ID in any other way except as a test for equality.
  296.  
  297. On the other hand, if using a "reliable" transport such as TCP, the
  298. application can infer from a reply message that the procedure was executed
  299. exactly once, but if it receives no reply message, it cannot assume that
  300. the remote procedure was not executed.  Note that even if a connection-
  301. oriented protocol like TCP is used, an application still needs time-outs
  302. and reconnection to handle server crashes.
  303.  
  304. There are other possibilities for transports besides datagram- or
  305. connection-oriented protocols.  For example, a request-reply protocol such
  306. as VMTP [2] is perhaps a natural transport for RPC.  ONC RPC uses both TCP
  307. and UDP transport protocols.  Section 10 (RECORD MARKING STANDARD)
  308.  
  309.  
  310.  
  311. Expires: February 28, 1996                                 [Page 5]
  312.  
  313.  
  314.  
  315. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  316.  
  317.  
  318. describes the mechanism employed by ONC RPC to utilize a connection-
  319. oriented, stream-oriented transport such as TCP.
  320.  
  321. 5. BINDING AND RENDEZVOUS INDEPENDENCE
  322.  
  323. The act of binding a particular client to a particular service and
  324. transport parameters is NOT part of this RPC protocol specification.  This
  325. important and necessary function is left up to some higher-level software.
  326. The recommended methods for binding are documented in "Binding Protocols
  327. for ONC RPC Version 2" [8].
  328.  
  329. Implementors could think of the RPC protocol as the jump-subroutine
  330. instruction ("JSR") of a network; the loader (binder) makes JSR useful, and
  331. the loader itself uses JSR to accomplish its task.  Likewise, the binding
  332. software makes RPC useful, possibly using RPC to accomplish this task.
  333.  
  334. 6. AUTHENTICATION
  335.  
  336. The RPC protocol provides the fields necessary for a client to identify
  337. itself to a service, and vice-versa, in each call and reply message.
  338. Security and access control mechanisms can be built on top of this message
  339. authentication.  Several different authentication protocols can be
  340. supported.  A field in the RPC header indicates which protocol is being
  341. used. More information on specific authentication protocols is in section
  342. 9: "Authentication Protocols".
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.  
  361.  
  362.  
  363.  
  364.  
  365.  
  366.  
  367.  
  368.  
  369.  
  370.  
  371.  
  372.  
  373.  
  374. Expires: February 28, 1996                                 [Page 6]
  375.  
  376.  
  377.  
  378. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  379.  
  380.  
  381. 7. RPC PROTOCOL REQUIREMENTS
  382.  
  383. The RPC protocol must provide for the following:
  384.  
  385. (1) Unique specification of a procedure to be called.
  386. (2) Provisions for matching response messages to request messages.
  387. (3) Provisions for authenticating the caller to service and vice-
  388.     versa.
  389.  
  390. Besides these requirements, features that detect the following are worth
  391. supporting because of protocol roll-over errors, implementation bugs, user
  392. error, and network administration:
  393.  
  394. (1) RPC protocol mismatches.
  395. (2) Remote program protocol version mismatches.
  396. (3) Protocol errors (such as misspecification of a procedure's
  397.     parameters).
  398. (4) Reasons why remote authentication failed.
  399. (5) Any other reasons why the desired procedure was not called.
  400.  
  401. 7.1 RPC Programs and Procedures
  402.  
  403. The RPC call message has three unsigned integer fields -- remote program
  404. number, remote program version number, and remote procedure number -- which
  405. uniquely identify the procedure to be called.  Program numbers are
  406. administered by a central authority (iana@isi.edu).  Once implementors have
  407. a program number, they can implement their remote program; the first
  408. implementation would most likely have the version number 1.  Because most
  409. new protocols evolve, a version field of the call message identifies which
  410. version of the protocol the caller is using.  Version numbers enable
  411. support of both old and new protocols through the same server process.
  412.  
  413. The procedure number identifies the procedure to be called.  These numbers
  414. are documented in the specific program's protocol specification.  For
  415. example, a file service's protocol specification may state that its
  416. procedure number 5 is "read" and procedure number 12 is "write".
  417.  
  418. Just as remote program protocols may change over several versions, the
  419. actual RPC message protocol could also change.  Therefore, the call message
  420. also has in it the RPC version number, which is always equal to two for the
  421. version of RPC described here.
  422.  
  423. The reply message to a request message has enough information to
  424. distinguish the following error conditions:
  425.  
  426. (1) The remote implementation of RPC does not support protocol version 2.
  427. The lowest and highest supported RPC version numbers are returned.
  428.  
  429. (2) The remote program is not available on the remote system.
  430.  
  431. (3) The remote program does not support the requested version number.  The
  432. lowest and highest supported remote program version numbers are returned.
  433.  
  434.  
  435.  
  436.  
  437. Expires: February 28, 1996                                 [Page 7]
  438.  
  439.  
  440.  
  441. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  442.  
  443.  
  444. (4) The requested procedure number does not exist.  (This is usually a
  445. client side protocol or programming error.)
  446.  
  447. (5) The parameters to the remote procedure appear to be garbage from the
  448. server's point of view.  (Again, this is usually caused by a disagreement
  449. about the protocol between client and service.)
  450.  
  451. 7.2 Authentication
  452.  
  453. Provisions for authentication of caller to service and vice-versa are
  454. provided as a part of the RPC protocol.  The call message has two
  455. authentication fields, the credential and verifier.  The reply message has
  456. one authentication field, the response verifier.  The RPC protocol
  457. specification defines all three fields to be the following opaque type (in
  458. the External Data Representation (XDR) language [10]):
  459.  
  460.       enum auth_flavor {
  461.          AUTH_NONE       = 0,
  462.          AUTH_SYS        = 1,
  463.          AUTH_SHORT      = 2,
  464.          AUTH_DH         = 3,   /* Diffie-Hellman Authentication */
  465.          AUTH_KERB4      = 4    /* Kerberos V4 Authentication */
  466.          /* and more to be defined */
  467.       };
  468.  
  469.       struct opaque_auth {
  470.          auth_flavor flavor;
  471.          opaque body<400>;
  472.       };
  473.  
  474. In other words, any "opaque_auth" structure is an "auth_flavor" enumeration
  475. followed by up to 400 bytes which are opaque to (uninterpreted by) the RPC
  476. protocol implementation.
  477.  
  478. The interpretation and semantics of the data contained within the
  479. authentication fields is specified by individual, independent
  480. authentication protocol specifications.  (Section 9 defines the various
  481. authentication protocols.)
  482.  
  483. If authentication parameters were rejected, the reply message contains
  484. information stating why they were rejected.
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500. Expires: February 28, 1996                                 [Page 8]
  501.  
  502.  
  503.  
  504. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  505.  
  506.  
  507. 7.3 Program Number Assignment
  508.  
  509. Program numbers are given out in groups of hexadecimal 20000000 (decimal
  510. 536870912) according to the following chart:
  511.  
  512.               0 - 1fffffff   assigned by iana@isi.edu
  513.        20000000 - 3fffffff   defined by user
  514.        40000000 - 5fffffff   transient
  515.        60000000 - 7fffffff   reserved
  516.        80000000 - 9fffffff   reserved
  517.        a0000000 - bfffffff   reserved
  518.        c0000000 - dfffffff   reserved
  519.        e0000000 - ffffffff   reserved
  520.  
  521. The first group is a range of numbers administered by the Internet Assigned
  522. Number Authority, iana@isi.edu [9], and should be identical for all sites.
  523. The second range is for applications peculiar to a particular site.  This
  524. range is intended primarily for debugging new programs.  When a site
  525. develops an application that might be of general interest, that application
  526. should request an assigned number in the first range.  Application
  527. developers may apply for blocks of RPC program numbers in the first range
  528. by sending electronic mail to "iana@isi.edu".  The third group is for
  529. applications that generate program numbers dynamically.  The final groups
  530. are reserved for future use, and should not be used.
  531.  
  532. 7.4 Other Uses of the RPC Protocol
  533.  
  534. The intended use of this protocol is for calling remote procedures.
  535. Normally, each call message is matched with a reply message.  However, the
  536. protocol itself is a message-passing protocol with which other (non-
  537. procedure call) protocols can be implemented.
  538.  
  539. 7.4.1 Batching
  540.  
  541. Batching is useful when a client wishes to send an arbitrarily large
  542. sequence of call messages to a server.  Batching typically uses reliable
  543. byte stream protocols (like TCP) for its transport.  In the case of
  544. batching, the client never waits for a reply from the server, and the
  545. server does not send replies to batch calls.  A sequence of batch calls is
  546. usually terminated by a legitimate remote procedure call operation in order
  547. to flush the pipeline and get positive acknowledgement.
  548.  
  549. 7.4.2 Broadcast Remote Procedure Calls
  550.  
  551. In broadcast protocols, the client sends a broadcast call to the network
  552. and waits for numerous replies.  This requires the use of packet-based
  553. protocols (like UDP) as its transport protocol.  Servers that support
  554. broadcast protocols usually respond only when the call is successfully
  555. processed and are silent in the face of errors, but this varies with the
  556. application.
  557.  
  558. The principles of broadcast RPC also apply to multicasting - an RPC request
  559. can be sent to a multicast address.
  560.  
  561.  
  562.  
  563. Expires: February 28, 1996                                 [Page 9]
  564.  
  565.  
  566.  
  567. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  568.  
  569.  
  570. 8. THE RPC MESSAGE PROTOCOL
  571.  
  572. This section defines the RPC message protocol in the XDR data description
  573. language [10].
  574.  
  575.       enum msg_type {
  576.          CALL  = 0,
  577.          REPLY = 1
  578.       };
  579.  
  580. A reply to a call message can take on two forms: The message was either
  581. accepted or rejected.
  582.  
  583.       enum reply_stat {
  584.          MSG_ACCEPTED = 0,
  585.          MSG_DENIED   = 1
  586.       };
  587.  
  588. Given that a call message was accepted, the following is the status of an
  589. attempt to call a remote procedure.
  590.  
  591.       enum accept_stat {
  592.          SUCCESS       = 0, /* RPC executed successfully             */
  593.          PROG_UNAVAIL  = 1, /* remote hasn't exported program        */
  594.          PROG_MISMATCH = 2, /* remote can't support version #        */
  595.          PROC_UNAVAIL  = 3, /* program can't support procedure       */
  596.          GARBAGE_ARGS  = 4, /* procedure can't decode params         */
  597.          SYSTEM_ERR    = 5  /* errors like memory allocation failure */
  598.       };
  599.  
  600. Reasons why a call message was rejected:
  601.  
  602.       enum reject_stat {
  603.          RPC_MISMATCH = 0, /* RPC version number != 2          */
  604.          AUTH_ERROR = 1    /* remote can't authenticate caller */
  605.       };
  606.  
  607. Why authentication failed:
  608.  
  609.       enum auth_stat {
  610.          AUTH_OK           = 0,  /* success                          */
  611.          /*
  612.           * failed at remote end
  613.           */
  614.          AUTH_BADCRED      = 1,  /* bad credential (seal broken)     */
  615.          AUTH_REJECTEDCRED = 2,  /* client must begin new session    */
  616.          AUTH_BADVERF      = 3,  /* bad verifier (seal broken)       */
  617.          AUTH_REJECTEDVERF = 4,  /* verifier expired or replayed     */
  618.          AUTH_TOOWEAK      = 5,  /* rejected for security reasons    */
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626. Expires: February 28, 1996                                [Page 10]
  627.  
  628.  
  629.  
  630. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  631.  
  632.  
  633.          /*
  634.           * failed locally
  635.           */
  636.          AUTH_INVALIDRESP  = 6,  /* bogus response verifier          */
  637.          AUTH_FAILED       = 7,  /* reason unknown                   */
  638.          /*
  639.           * kerberos errors
  640.           */
  641.          AUTH_KERB_GENERIC = 8,  /* kerberos generic error           */
  642.          AUTH_TIMEEXPIRE   = 9,  /* time of credential expired       */
  643.          AUTH_TKT_FILE     = 10, /* something wrong with ticket file */
  644.          AUTH_DECODE       = 11, /* can't decode authenticator       */
  645.          AUTH_NET_ADDR     = 12  /* wrong net address in ticket      */
  646.       };
  647.  
  648. The RPC message:
  649.  
  650. All messages start with a transaction identifier, XID, followed by a two-
  651. armed discriminated union.  The union's discriminant is a msg_type which
  652. switches to one of the two types of the message.  The XID of a REPLY
  653. message always matches that of the initiating CALL message.
  654.  
  655. From the client's perspective, XIDs associate RPC replys with calls which
  656. the client has previously sent.  From the server's perspective, XIDs are
  657. used to detect retransmissions of RPC calls to which it has previously
  658. replied.  Implementations are advised to take precautions to ensure that an
  659. XID is valid within a client-server RPC session by checking that other
  660. parameters match, such as RPC program number and RPC version number.
  661. Implementations may also want to check that the transport-layer end-points
  662. agree, such as the IP address and port number in the TCP/IP protocol stack.
  663.  
  664. NB:  The XID field is only used for clients matching reply messages with
  665. call messages or for servers detecting retransmissions; the service side
  666. cannot treat the XID as any type of sequence number.
  667.  
  668.       struct rpc_msg {
  669.          unsigned int xid;      /* Transaction identifier (XID) */
  670.          union switch (msg_type mtype) {
  671.          case CALL:
  672.             call_body cbody;
  673.          case REPLY:
  674.             reply_body rbody;
  675.          } body;
  676.       };
  677.  
  678. Body of an RPC call:
  679.  
  680. In version 2 of the RPC protocol specification, rpcvers must be equal to 2.
  681. The fields prog, vers, and proc specify the remote program, its version
  682. number, and the procedure within the remote program to be called.  After
  683. these fields are two authentication parameters:  cred (authentication
  684. credential) and verf (authentication verifier).  The two authentication
  685. parameters are followed by the parameters to the remote procedure, which
  686.  
  687.  
  688.  
  689. Expires: February 28, 1996                                [Page 11]
  690.  
  691.  
  692.  
  693. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  694.  
  695.  
  696. are specified by the specific program protocol.
  697.  
  698. The purpose of the authentication verifier is to validate the
  699. authentication credential.  Note that these two items are historically
  700. separate, but are always used together as one logical entity.
  701.  
  702.       struct call_body {
  703.          unsigned int rpcvers;       /* must be equal to two (2) */
  704.          unsigned int prog;
  705.          unsigned int vers;
  706.          unsigned int proc;
  707.          opaque_auth  cred;
  708.          opaque_auth  verf;
  709.          /* procedure specific parameters start here */
  710.       };
  711.  
  712. Body of a reply to an RPC call:
  713.  
  714.       union reply_body switch (reply_stat stat) {
  715.       case MSG_ACCEPTED:
  716.          accepted_reply areply;
  717.       case MSG_DENIED:
  718.          rejected_reply rreply;
  719.       } reply;
  720.  
  721. Reply to an RPC call that was accepted by the server:
  722.  
  723. There could be an error even though the call was accepted.  The first field
  724. is an authentication verifier that the server generates in order to
  725. validate itself to the client.  It is followed by a union whose
  726. discriminant is an enum accept_stat.  The SUCCESS arm of the union is
  727. protocol specific.  The PROG_UNAVAIL, PROC_UNAVAIL, GARBAGE_ARGS, and
  728. SYSTEM_ERR arms of the union are void.  The PROG_MISMATCH arm specifies the
  729. lowest and highest version numbers of the remote program supported by the
  730. server.
  731.  
  732.       struct accepted_reply {
  733.          opaque_auth verf;
  734.          union switch (accept_stat stat) {
  735.          case SUCCESS:
  736.             opaque results[0];
  737.             /*
  738.              * procedure-specific results start here
  739.              */
  740.           case PROG_MISMATCH:
  741.              struct {
  742.                 unsigned int low;
  743.                 unsigned int high;
  744.              } mismatch_info;
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752. Expires: February 28, 1996                                [Page 12]
  753.  
  754.  
  755.  
  756. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  757.  
  758.  
  759.           default:
  760.              /*
  761.               * Void.  Cases include PROG_UNAVAIL, PROC_UNAVAIL,
  762.               * GARBAGE_ARGS, and SYSTEM_ERR.
  763.               */
  764.              void;
  765.           } reply_data;
  766.       };
  767.  
  768. Reply to an RPC call that was rejected by the server:
  769.  
  770. The call can be rejected for two reasons: either the server is not running
  771. a compatible version of the RPC protocol (RPC_MISMATCH), or the server
  772. rejects the identity of the caller (AUTH_ERROR). In case of an RPC version
  773. mismatch, the server returns the lowest and highest supported RPC version
  774. numbers.  In case of invalid authentication, failure status is returned.
  775.  
  776.       union rejected_reply switch (reject_stat stat) {
  777.       case RPC_MISMATCH:
  778.          struct {
  779.             unsigned int low;
  780.             unsigned int high;
  781.          } mismatch_info;
  782.       case AUTH_ERROR:
  783.          auth_stat stat;
  784.       };
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815. Expires: February 28, 1996                                [Page 13]
  816.  
  817.  
  818.  
  819. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  820.  
  821.  
  822. 9. AUTHENTICATION PROTOCOLS
  823.  
  824. As previously stated, authentication parameters are opaque, but open-ended
  825. to the rest of the RPC protocol.  This section defines two standard
  826. "flavors" of authentication.  Implementors are free to invent new
  827. authentication types, with the same rules of flavor number assignment as
  828. there is for program number assignment.  The "flavor" of a credential or
  829. verifier refers to the value of the "flavor" field in the opaque_auth
  830. structure. Flavor numbers, like RPC program numbers, are also administered
  831. centrally, and developers may assign new flavor numbers by applying through
  832. electronic mail to "iana@isi.edu".  Credentials and verifiers are
  833. represented as variable length opaque data (the "body" field in the
  834. opaque_auth structure).
  835.  
  836. In this document, two flavors of authentication are described.  Of these,
  837. Null authentication (described in the next subsection) is mandatory - it
  838. must be available in all implementations.  System authentication is
  839. described in Appendix A.  It is strongly recommended that implementors
  840. include System authentication in their implementations.  Many applications
  841. use this style of authentication, and availability of this flavor in an
  842. implementation will enhance interoperability.
  843.  
  844. Note that neither Null authentication nor System authentication provide any
  845. security.  A "flavor"-based authentication system is provided in ONC RPC so
  846. that other, more secure, authentication protocols may be implemented in the
  847. future.
  848.  
  849. 9.1 Null Authentication
  850.  
  851. Often calls must be made where the client does not care about its identity
  852. or the server does not care who the client is.  In this case, the flavor of
  853. the RPC message's credential, verifier, and reply verifier is "AUTH_NONE".
  854. Opaque data associated with "AUTH_NONE" is undefined.  It is recommended
  855. that the length of the opaque data be zero.
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.  
  867.  
  868.  
  869.  
  870.  
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878. Expires: February 28, 1996                                [Page 14]
  879.  
  880.  
  881.  
  882. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  883.  
  884.  
  885. 10. RECORD MARKING STANDARD
  886.  
  887. When RPC messages are passed on top of a byte stream transport protocol
  888. (like TCP), it is necessary to delimit one message from another in order to
  889. detect and possibly recover from protocol errors.  This is called record
  890. marking (RM).  One RPC message fits into one RM record.
  891.  
  892. A record is composed of one or more record fragments.  A record fragment is
  893. a four-byte header followed by 0 to (2**31) - 1 bytes of fragment data.
  894. The bytes encode an unsigned binary number; as with XDR integers, the byte
  895. order is from highest to lowest.  The number encodes two values -- a
  896. boolean which indicates whether the fragment is the last fragment of the
  897. record (bit value 1 implies the fragment is the last fragment) and a 31-bit
  898. unsigned binary value which is the length in bytes of the fragment's data.
  899. The boolean value is the highest-order bit of the header; the length is the
  900. 31 low-order bits.  (Note that this record specification is NOT in XDR
  901. standard form!)
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941. Expires: February 28, 1996                                [Page 15]
  942.  
  943.  
  944.  
  945. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  946.  
  947.  
  948. 11. THE RPC LANGUAGE
  949.  
  950. Just as there was a need to describe the XDR data-types in a formal
  951. language, there is also need to describe the procedures that operate on
  952. these XDR data-types in a formal language as well.  The RPC Language is an
  953. extension to the XDR language, with the addition of "program", "procedure",
  954. and "version" declarations.  The following example is used to describe the
  955. essence of the language.
  956.  
  957. 11.1 An Example Service Described in the RPC Language
  958.  
  959. Here is an example of the specification of a simple ping program.
  960.  
  961.    program PING_PROG {
  962.          /*
  963.           * Latest and greatest version
  964.           */
  965.          version PING_VERS_PINGBACK {
  966.             void
  967.             PINGPROC_NULL(void) = 0;
  968.  
  969.             /*
  970.              * Ping the client, return the round-trip time
  971.              * (in microseconds). Returns -1 if the operation
  972.              * timed out.
  973.              */
  974.             int
  975.             PINGPROC_PINGBACK(void) = 1;
  976.          } = 2;
  977.  
  978.          /*
  979.           * Original version
  980.           */
  981.          version PING_VERS_ORIG {
  982.             void
  983.             PINGPROC_NULL(void) = 0;
  984.          } = 1;
  985.       } = 1;
  986.  
  987.       const PING_VERS = 2;      /* latest version */
  988.  
  989. The first version described is PING_VERS_PINGBACK with two procedures,
  990. PINGPROC_NULL and PINGPROC_PINGBACK.  PINGPROC_NULL takes no arguments and
  991. returns no results, but it is useful for computing round-trip times from
  992. the client to the server and back again.  By convention, procedure 0 of any
  993. RPC protocol should have the same semantics, and never require any kind of
  994. authentication.  The second procedure is used for the client to have the
  995. server do a reverse ping operation back to the client, and it returns the
  996. amount of time (in microseconds) that the operation used.  The next
  997. version, PING_VERS_ORIG, is the original version of the protocol and it
  998. does not contain PINGPROC_PINGBACK procedure. It is useful for
  999. compatibility with old client programs, and as this program matures it may
  1000. be dropped from the protocol entirely.
  1001.  
  1002.  
  1003.  
  1004. Expires: February 28, 1996                                [Page 16]
  1005.  
  1006.  
  1007.  
  1008. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  1009.  
  1010.  
  1011. 11.2 The RPC Language Specification
  1012.  
  1013. The RPC language is identical to the XDR language defined in RFC 1014,
  1014. except for the added definition of a "program-def" described below.
  1015.  
  1016. program-def:
  1017.    "program" identifier "{"
  1018.       version-def
  1019.       version-def *
  1020.    "}" "=" constant ";"
  1021.  
  1022. version-def:
  1023.    "version" identifier "{"
  1024.        procedure-def
  1025.        procedure-def *
  1026.    "}" "=" constant ";"
  1027.  
  1028. procedure-def:
  1029.    type-specifier identifier "(" type-specifier
  1030.      ("," type-specifier )* ")" "=" constant ";"
  1031.  
  1032. 11.3 Syntax Notes
  1033.  
  1034. (1) The following keywords are added and cannot be used as identifiers:
  1035. "program" and "version";
  1036.  
  1037. (2) A version name cannot occur more than once within the scope of a
  1038. program definition. Nor can a version number occur more than once within
  1039. the scope of a program definition.
  1040.  
  1041. (3) A procedure name cannot occur more than once within the scope of a
  1042. version definition. Nor can a procedure number occur more than once within
  1043. the scope of version definition.
  1044.  
  1045. (4) Program identifiers are in the same name space as constant and type
  1046. identifiers.
  1047.  
  1048. (5) Only unsigned constants can be assigned to programs, versions and
  1049. procedures.
  1050.  
  1051. 12. SECURITY CONSIDERATIONS
  1052.  
  1053. Security considerations are discussed in Section 9 and Section 13 (APPENDIX
  1054. A).
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066.  
  1067. Expires: February 28, 1996                                [Page 17]
  1068.  
  1069.  
  1070.  
  1071. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  1072.  
  1073.  
  1074. 13. APPENDIX A: SYSTEM AUTHENTICATION
  1075.  
  1076. The client may wish to identify itself, for example, as it is identified on
  1077. a UNIX(tm) system.  The flavor of the client credential is "AUTH_SYS".  The
  1078. opaque data constituting the credential encodes the following structure:
  1079.  
  1080.       struct authsys_parms {
  1081.          unsigned int stamp;
  1082.          string machinename<255>;
  1083.          unsigned int uid;
  1084.          unsigned int gid;
  1085.          unsigned int gids<16>;
  1086.       };
  1087.  
  1088. The "stamp" is an arbitrary ID which the caller machine may generate.  The
  1089. "machinename" is the name of the caller's machine (like "krypton").  The
  1090. "uid" is the caller's effective user ID.  The "gid" is the caller's
  1091. effective group ID.  The "gids" is a counted array of groups which contain
  1092. the caller as a member.  The verifier accompanying the credential should
  1093. have "AUTH_NONE" flavor value (defined above).  Note this credential is
  1094. only unique within a particular domain of machine names, uids, and gids.
  1095.  
  1096. The flavor value of the verifier received in the reply message from the
  1097. server may be "AUTH_NONE" or "AUTH_SHORT".  In the case of "AUTH_SHORT",
  1098. the bytes of the reply verifier's string encode an opaque structure.  This
  1099. new opaque structure may now be passed to the server instead of the
  1100. original "AUTH_SYS" flavor credential.  The server may keep a cache which
  1101. maps shorthand opaque structures (passed back by way of an "AUTH_SHORT"
  1102. style reply verifier) to the original credentials of the caller.  The
  1103. caller can save network bandwidth and server cpu cycles by using the
  1104. shorthand credential.
  1105.  
  1106. The server may flush the shorthand opaque structure at any time.  If this
  1107. happens, the remote procedure call message will be rejected due to an
  1108. authentication error.  The reason for the failure will be
  1109. "AUTH_REJECTEDCRED".  At this point, the client may wish to try the
  1110. original "AUTH_SYS" style of credential.
  1111.  
  1112. It should be noted that use of this flavor of authentication does not
  1113. guarantee any security for the users or providers of a service, in itself.
  1114. The authentication provided by this scheme can be considered legitimate
  1115. only when applications using this scheme and the network can be secured
  1116. externally, and privileged transport addresses are used for the
  1117. communicating end-points (an example of this is the use of privileged
  1118. TCP/UDP ports in Unix systems - note that not all systems enforce
  1119. privileged transport address mechanisms).
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130. Expires: February 28, 1996                                [Page 18]
  1131.  
  1132.  
  1133.  
  1134. INTERNET-DRAFT   Remote Procedure Call Protocol Version 2      28-August-96
  1135.  
  1136.  
  1137. 14. REFERENCES
  1138.  
  1139. [1]  Birrell, A. D.  & Nelson, B. J., "Implementing Remote Procedure
  1140.      Calls", XEROX CSL-83-7, October 1983.
  1141.  
  1142. [2]  Cheriton, D., "VMTP: Versatile Message Transaction Protocol:
  1143.      Protocol Specification", RFC-1045, Stanford University, February
  1144.      1988.
  1145.  
  1146. [3]  Diffie & Hellman, "New Directions in Cryptography", IEEE
  1147.      Transactions on Information Theory IT-22, November 1976.
  1148.  
  1149. [4]  Mills, D., "Network Time Protocol (Version 3)", RFC-1305,
  1150.      University of Delaware, March 1992.
  1151.  
  1152. [5]  National Bureau of Standards, "Data Encryption Standard", Federal
  1153.      Information Processing Standards Publication 46, January 1977.
  1154.  
  1155. [6]  Postel, J., "Transmission Control Protocol - DARPA Internet
  1156.      Program Protocol Specification", RFC-793, Information Sciences
  1157.      Institute, September 1981.
  1158.  
  1159. [7]  Postel, J., "User Datagram Protocol", RFC-768, Information
  1160.      Sciences Institute, August 1980.
  1161.  
  1162. [8]  Srinivasan, R., "Binding Protocols for ONC RPC Version 2",
  1163.      RFC-1833, Sun Microsystems, 1995.
  1164.  
  1165. [9]  Reynolds, J., and Postel, J., "Assigned Numbers", STD-2, RFC-1700,
  1166.      Information Sciences Institute, October 1994.
  1167.  
  1168. [10] Srinivasan, R.,  "XDR: External Data Representation Standard",
  1169.      RFC-1832, Sun Microsystems, 1995.
  1170.  
  1171. 15. AUTHOR'S ADDRESS
  1172.  
  1173. Stephen X. Nahm
  1174. Sun Microsystems, Inc.
  1175. 2550 Garcia Avenue
  1176. Mountain View, CA 94043
  1177.  
  1178. Phone: +1 (415) 786-5086
  1179.  
  1180. E-mail: sxn@sun.com
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193. Expires: February 28, 1996                                [Page 19]
  1194.