.\".\" Must use  --  tbl  --  with this one.\".\" @(#)rpc.rfc.ms	2.2 88/08/05 4.0 RPCSRC.de BT.if \\n%=1 .tl ''- % -''...ND.\" prevent excess underlining in nroff.if n .fp 2 R.OH 'Remote Procedure Calls: Protocol Specification''Page %'.EH 'Page %''Remote Procedure Calls: Protocol Specification'.if \\n%=1 .bp.SH\&Remote Procedure Calls: Protocol Specification.LP.NH 0\&Status of this Memo.LPNote: This chapter specifies a protocol that Sun Microsystems, Inc.,and others are using.  It has been designated RFC1050 by the ARPA NetworkInformation Center..LP.NH 1\&Introduction.LPThis chapter specifies  a  message protocol  used in implementingSun's Remote Procedure Call (RPC) package.  (The message protocol isspecified with the External Data Representation (XDR) language.See the.I "External Data Representation Standard: Protocol Specification"for the details.  Here, we assume that  the  reader is familiar  with XDR and do not attempt to justify it or its uses).  The paperby Birrell and Nelson [1]  is recommended as an  excellent backgroundto  and justification of RPC..NH 2\&Terminology.LPThis chapter discusses servers, services, programs, procedures,clients, and versions.  A server is a piece of software where networkservices are implemented.  A network service is a collection of oneor more remote programs.  A remote program implements one or moreremote procedures; the procedures, their parameters, and results aredocumented in the specific program's protocol specification (see the\fIPort Mapper Program Protocol\fP\, below, for an example).  Networkclients are pieces of software that initiate remote procedure callsto services.  A server may support more than one version of a remoteprogram in order to be forward compatible with changing protocols..LPFor example, a network file service may be composed of two programs.One program may deal with high-level applications such as file systemaccess control and locking.  The other may deal with low-level fileIO and have procedures like "read" and "write".  A client machine ofthe network file service would call the procedures associated withthe two programs of the service on behalf of some user on the clientmachine..NH 2\&The RPC Model.LPThe remote procedure call model is similar to the local procedurecall model.  In the local case, the caller places arguments to aprocedure in some well-specified location (such as a resultregister).  It then transfers control to the procedure, andeventually gains back control.  At that point, the results of theprocedure are extracted from the well-specified location, and thecaller continues execution..LPThe remote procedure call is similar, in that one thread of controllogically winds through two processes\(emone is the caller's process,the other is a server's process.  That is, the caller process sends acall message to the server process and waits (blocks) for a replymessage.  The call message contains the procedure's parameters, amongother things.  The reply message contains the procedure's results,among other things.  Once the reply message is received, the resultsof the procedure are extracted, and caller's execution is resumed..LPOn the server side, a process is dormant awaiting the arrival of acall message.  When one arrives, the server process extracts theprocedure's parameters, computes the results, sends a reply message,and then awaits the next call message..LPNote that in this model, only one of the two processes is active atany given time.  However, this model is only given as an example.The RPC protocol makes no restrictions on the concurrency modelimplemented, and others are possible.  For example, an implementationmay choose to have RPC calls be asynchronous, so that the client maydo useful work while waiting for the reply from the server.  Anotherpossibility is to have the server create a task to process anincoming request, so that the server can be free to receive otherrequests..NH 2\&Transports and Semantics.LPThe RPC protocol is independent of transport protocols.  That is, RPCdoes not care how a message is passed from one process to another.The protocol deals only with specification and interpretation ofmessages..LPIt is important to point out that RPC does not try to implement anykind of reliability and that the application must be aware of thetype of transport protocol underneath RPC.  If it knows it is runningon top of a reliable transport such as TCP/IP[6], then most of thework is already done for it.  On the other hand, if it is running ontop of an unreliable transport such as UDP/IP[7], it must implementis own retransmission and time-out policy as the RPC layer does notprovide this service..LPBecause of transport independence, the RPC protocol does not attachspecific semantics to the remote procedures or their execution.Semantics can be inferred from (but should be explicitly specifiedby) the underlying transport protocol.  For example, consider RPCrunning on top of an unreliable transport such as UDP/IP.  If anapplication retransmits RPC messages after short time-outs, the onlything it can infer if it receives no reply is that the procedure wasexecuted zero or more times.  If it does receive a reply, then it caninfer that the procedure was executed at least once..LPA server may wish to remember previously granted requests from aclient and not regrant them in order to insure some degree ofexecute-at-most-once semantics.  A server can do this by takingadvantage of the transaction ID that is packaged with every RPCrequest.  The main use of this transaction is by the client RPC layerin matching replies to requests.  However, a client application maychoose to reuse its previous transaction ID when retransmitting arequest.  The server application, knowing this fact, may choose toremember this ID after granting a request and not regrant requestswith the same ID in order to achieve some degree ofexecute-at-most-once semantics.  The server is not allowed to examinethis ID in any other way except as a test for equality..LPOn the other hand, if using a reliable transport such as TCP/IP, theapplication can infer from a reply message that the procedure wasexecuted exactly once, but if it receives no reply message, it cannotassume the remote procedure was not executed.  Note that even if aconnection-oriented protocol like TCP is used, an application stillneeds time-outs and reconnection to handle server crashes..LPThere are other possibilities for transports besides datagram- orconnection-oriented protocols.  For example, a request-reply protocolsuch as VMTP[2] is perhaps the most natural transport for RPC..SH.INOTE:  At Sun, RPC is currently implemented on top of both TCP/IPand UDP/IP transports..LP.NH 2\&Binding and Rendezvous Independence.LPThe act of binding a client to a service is NOT part of the remoteprocedure call specification.  This important and necessary functionis left up to some higher-level software.  (The software may use RPCitself\(emsee the \fIPort Mapper Program Protocol\fP\, below)..LPImplementors should think of the RPC protocol as the jump-subroutineinstruction ("JSR") of a network; the loader (binder) makes JSRuseful, and the loader itself uses JSR to accomplish its task.Likewise, the network makes RPC useful, using RPC to accomplish thistask..NH 2\&Authentication.LPThe RPC protocol provides the fields necessary for a client toidentify itself to a service and vice-versa.  Security and accesscontrol mechanisms can be built on top of the message authentication.Several different authentication protocols can be supported.  A fieldin the RPC header indicates which protocol is being used.  Moreinformation on specific authentication protocols can be found in the\fIAuthentication Protocols\fP\,below..KS.NH 1\&RPC Protocol Requirements.LPThe RPC protocol must provide for the following:.IP  1.Unique specification of a procedure to be called..IP  2.Provisions for matching response messages to request messages..KE.IP  3.Provisions for authenticating the caller to service and vice-versa..LPBesides these requirements, features that detect the following areworth supporting because of protocol roll-over errors, implementationbugs, user error, and network administration:.IP  1.RPC protocol mismatches..IP  2.Remote program protocol version mismatches..IP  3.Protocol errors (such as misspecification of a procedure's parameters)..IP  4.Reasons why remote authentication failed..IP  5.Any other reasons why the desired procedure was not called..NH 2\&Programs and Procedures.LPThe RPC call message has three unsigned fields:  remote programnumber, 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 (likeSun).  Once an implementor has a program number, he can implement hisremote program; the first implementation would most likely have theversion number of 1.  Because most new protocols evolve into better,stable, and mature protocols, a version field of the call messageidentifies which version of the protocol the caller is using.Version numbers make speaking old and new protocols through the sameserver process possible..LPThe procedure number identifies the procedure to be called.  Thesenumbers are documented in the specific program's protocolspecification.  For example, a file service's protocol specificationmay state that its procedure number 5 is "read" and procedure number12 is "write"..LPJust as remote program protocols may change over several versions,the actual RPC message protocol could also change.  Therefore, thecall message also has in it the RPC version number, which is alwaysequal to two for the version of RPC described here..LPThe reply message to a request  message  has enough  information todistinguish the following error conditions:.IP  1.The remote implementation of RPC does speak protocol version 2.The lowest and highest supported RPC version numbers are returned..IP  2.The remote program is not available on the remote system..IP  3.The remote program does not support the requested version number.The lowest and highest supported remote program version numbers arereturned..IP  4.The requested procedure number does not exist.  (This is usually acaller side protocol or programming error.).IP  5.The parameters to the remote procedure appear to be garbage from theserver's point of view.  (Again, this is usually caused by adisagreement about the protocol between client and service.).NH 2\&Authentication.LPProvisions for authentication of caller to service and vice-versa areprovided as a part of the RPC protocol.  The call message has twoauthentication fields, the credentials and verifier.  The replymessage has one authentication field, the response verifier.  The RPCprotocol specification defines all three fields to be the followingopaque type:.DS.ft CW.vs 11enum auth_flavor {    AUTH_NULL        = 0,    AUTH_UNIX        = 1,    AUTH_SHORT       = 2,    AUTH_DES         = 3    /* \fIand more to be defined\fP */};struct opaque_auth {    auth_flavor flavor;    opaque body<400>;};.DE.LPIn simple English, any.I opaque_auth structure is an .I auth_flavor enumeration followed by bytes which are  opaque to the RPC protocolimplementation..LPThe interpretation and semantics  of the data contained  within theauthentication   fields  is specified  by  individual,  independentauthentication  protocol specifications.   (See \fIAuthentication Protocols\fP\,below, for definitions of the various authentication protocols.).LPIf authentication parameters were   rejected, the  response messagecontains information stating why they were rejected..NH 2\&Program Number Assignment.LPProgram numbers are given out in groups of.I 0x20000000 (decimal 536870912) according to the following chart:.TSbox tab (&) ;lfI lfIrfL cfI .Program Numbers&Description_.sp .50 - 1fffffff&Defined by Sun20000000 - 3fffffff&Defined by user40000000 - 5fffffff&Transient60000000 - 7fffffff&Reserved80000000 - 9fffffff&Reserveda0000000 - bfffffff&Reservedc0000000 - dfffffff&Reservede0000000 - ffffffff&Reserved.TE.LPThe first group is a range of numbers administered by SunMicrosystems and should be identical for all sites.  The second rangeis for applications peculiar to a particular site.  This range isintended primarily for debugging new programs.  When a site developsan application that might be of general interest, that applicationshould be given an assigned number in the first range.  The thirdgroup is for applications that generate program numbers dynamically.The final groups are reserved for future use, and should not be used..NH 2\&Other Uses of the RPC Protocol.LPThe 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 whichother (non-RPC) protocols can be implemented.  Sun currently uses, orperhaps 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..NH 3\&Batching.LPBatching allows a client to send an arbitrarily large sequence ofcall messages to a server; batching typically uses reliable bytestream protocols (like TCP/IP) for its transport.  In the case ofbatching, the client never waits for a reply from the server, and theserver does not send replies to batch requests.  A sequence of batchcalls is usually terminated by a legitimate RPC in order to flush thepipeline (with positive acknowledgement)..NH 3\&Broadcast RPC.LPIn broadcast RPC-based protocols, the client sends a broadcast packetto the network and waits for numerous replies.  Broadcast RPC usesunreliable, packet-based protocols (like UDP/IP) as its transports.Servers that support broadcast protocols only respond when therequest is successfully processed, and are silent in the face oferrors.  Broadcast RPC uses the Port Mapper RPC service to achieveits semantics.  See the \fIPort Mapper Program Protocol\fP\, below,for more information..KS.NH 1\&The RPC Message Protocol.LPThis section defines the RPC message protocol in the XDR datadescription language.  The message is defined in a top-down style..ie t .DS.el .DS L.ft CWenum msg_type {	CALL  = 0,	REPLY = 1};.ft I/** A reply to a call message can take on two forms:* The message was either accepted or rejected.*/.ft CWenum reply_stat {	MSG_ACCEPTED = 0,	MSG_DENIED   = 1};.ft I/** Given that a call message was accepted,  the following is the* status of an attempt to call a remote procedure.*/.ft CWenum accept_stat {	SUCCESS       = 0, /* \fIRPC executed successfully       \fP*/	PROG_UNAVAIL  = 1, /* \fIremote hasn't exported program  \fP*/	PROG_MISMATCH = 2, /* \fIremote can't support version #  \fP*/	PROC_UNAVAIL  = 3, /* \fIprogram can't support procedure \fP*/	GARBAGE_ARGS  = 4  /* \fIprocedure can't decode params   \fP*/};.DE.ie t .DS.el .DS L.ft I/** Reasons why a call message was rejected:*/.ft CWenum reject_stat {	RPC_MISMATCH = 0, /* \fIRPC version number != 2          \fP*/	AUTH_ERROR = 1    /* \fIremote can't authenticate caller \fP*/};.ft I/** Why authentication failed:*/.ft CWenum auth_stat {	AUTH_BADCRED      = 1,  /* \fIbad credentials \fP*/	AUTH_REJECTEDCRED = 2,  /* \fIclient must begin new session \fP*/	AUTH_BADVERF      = 3,  /* \fIbad verifier \fP*/	AUTH_REJECTEDVERF = 4,  /* \fIverifier expired or replayed  \fP*/	AUTH_TOOWEAK      = 5   /* \fIrejected for security reasons \fP*/};.DE.KE.ie t .DS.el .DS L.ft I/** 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 \fIREPLY\fP  message always* matches  that of the initiating \fICALL\fP   message.   NB: The xid* field is only  used for clients  matching reply messages with* call messages  or for servers detecting  retransmissions; the* service side  cannot treat this id  as any type   of sequence* number.*/.ft CWstruct rpc_msg {	unsigned int xid;	union switch (msg_type mtype) {		case CALL:			call_body cbody;		case REPLY:  			reply_body rbody;	} body;};.DE.ie t .DS